oi:exclude

Syntax

<element oi:exclude>
<element oi:exclude=subtree>
<element oi:exclude=shadowroot>

Value

(empty)

The element is ignored, including its own attributes, and so is its entire subtree, including shadow trees under it.

subtree

Changes to the element's own attributes still sync back. Changes below the element, such as items that a script appends, are ignored.

shadowroot Experimental

Everything inside the host's shadow tree is ignored, nested shadow roots included, and Shadow Source Materialization never writes it into the source. The host's own attributes and its light DOM still sync.

Any other value has no effect.

Description

With live output → input sync on, which is the default, the playground writes changes that scripts or the user make to the output's DOM back into your source. oi:exclude takes a part of the page out of that flow. The change still happens in the page, and the source stays as you wrote it. See From the page back to the source.

The oi: attributes act only on output → input sync. An excluded element still updates normally from your edits: a change to its text or its attributes in the editor is applied to the output like any other. The authored source of an excluded region normally stays exactly as written, and the one-time pull with F6 respects the exclusion too.

Usage notes

Containers that scripts fill

Use oi:exclude=subtree on a container that a script fills at run time, such as a log or a list of results. The items the script appends stay out of the source, while attributes of the container itself, such as a data-count that the script sets, still sync back. Use the empty form if the container's own attributes should stay out of the source too. Either way, write the container empty in your source, and let the script fill it.

Values that change all the time

Use the empty form on an element whose content a script updates continuously, such as a counter, so that each update is not written into the source.

Components and overlays

Runtime overlays, such as toasts, popovers and debug panels, belong in a closed shadow root or in an excluded container, not directly in <body>, where they would be adopted into the source. Writing IOSync-safe components shows the patterns.

Shadow roots

Open runtime shadow roots are ignored by output → input sync, unless Shadow Source Materialization (F7) is on. With it on, a pull would write them into the source as <template shadowrootmode=open>. Mark the host with oi:exclude=shadowroot to keep one component's shadow tree out of that. Closed shadow roots are never visible to the sync, so they need no mark.

Generated text

Experimental A few commands build the HTML of a selection from the live DOM, not from the source: Selection: Get HTML, Input: Fetch [i:] and Input: Empty [i:], and clipboard copies of copy:redact content. In the text they produce, an element with an empty oi:exclude is omitted, an element with oi:exclude=subtree is written without its children, and a host with oi:exclude=shadowroot loses its shadow template.

In deployments

Deploying does not strip oi:exclude, as it does the attributes that start with i:, o:, io:, edge:, h: and worker:. It stays in the HTML as an inert attribute with no effect. The other oi: attribute, oi:indent, is described on Global attributes.

Examples

A value that changes every second

Without oi:exclude, each tick would be written into the source. With it, the output counts and the source keeps the 0 you wrote.

<output id=n oi:exclude>0</output>
<script type=module>
  setInterval(() => n.value = +n.value + 1, 1000)
</script>

A list that a script fills

The appended list items stay out of the source even with live output → input sync on. A change to an attribute of #log itself, such as log.dataset.count = 3, still syncs back.

<ul id=log oi:exclude=subtree></ul>
<script type=module>
  setInterval(() => log.append(Object.assign(document.createElement('li'), { textContent: new Date().toLocaleTimeString() })), 1000)
</script>

A component whose shadow tree stays out of the source

Experimental With Shadow Source Materialization on, a pull would write the card's open shadow root into the source. oi:exclude=shadowroot prevents that, while the host's attributes still sync: an edit from title=Hi to title=Yo re-renders the heading, and nothing reaches the source.

<meta io:sync=x-card>
<x-card oi:exclude=shadowroot title=Hi></x-card>
<script type=module>
  customElements.define('x-card', class extends HTMLElement {
    static observedAttributes = ['title']
    #root = this.attachShadow({ mode: 'open' })
    attributeChangedCallback() { this.#root.replaceChildren(Object.assign(document.createElement('h2'), { textContent: this.title })) }
  })
</script>

Specifications

Not part of any specification. oi:exclude is an RTCode.io extension for the output → input sync of the playground. The shadow trees it refers to are shadow DOM trees.

Availability

See also

• Global attributes
• The IOSync model
• Live sync and reloads
• Writing IOSync-safe components
• sync
• <meta io:sync>