HTML declarative shadow DOM: parse a component boundary from markup

Last updated: 1 Oct 20267 min read

tutorial

A template with shadowrootmode can create a shadow root on its parent during HTML parsing.

Use it for a real task

A receipt card has internal structure and a named title slot, while the surrounding page supplies the actual receipt title. The template is parsed as a shadow root rather than shown as a spare fragment. The light-DOM heading remains the semantic content; the component boundary organizes styling and distribution. This is useful only when the component genuinely needs encapsulation.

<receipt-card>
  <template shadowrootmode="open">
    <article>
      <header><slot name="title">Receipt</slot></header>
      <slot></slot>
    </article>
  </template>
  <h2 slot="title">Receipt R-47</h2>
  <p>Held for review.</p>
</receipt-card>

What the markup guarantees

Declarative shadow roots depend on the HTML parser path; inserting this string through a generic HTML assignment does not necessarily create the same tree. The custom element name can remain unregistered while the parser handles the shadow root, but any interactive behavior still needs implementation.

Cost and limits

Shadow DOM adds a tree and styling boundary per instance. Repeating large templates on a list of hundreds of cards can expand the response, so compare it with plain semantic markup first.

Common Mistakes

Do not expect every string-to-DOM operation to activate a declarative shadow root.
Do not put essential text only inside a hidden fallback.
Do not add encapsulation where ordinary CSS scoping is enough.

Connected lessons

Related CSS decisions

html

advanced