liveBook · Manning

Declarative shadow root

As explained in Vanilla Web

An HTML feature for declaring a shadow root and its contents in markup rather than creating them with JavaScript.

A server-rendered component need not wait for JavaScript to gain a shadow tree. Declarative Shadow DOM lets the browser create a real shadow root while parsing HTML: place the component’s shadow content inside a <template> with a shadowrootmode attribute. The root exists before the custom element upgrades. section 9.6

<product-card>
  <template shadowrootmode="open"> #1
    <link rel="stylesheet" href="product-card.css">

    <div class="row">
      <p class="title"><slot name="title">Untitled</slot></p>
      <p class="price"><slot name="price">$0</slot></p>
    </div>

    <p class="muted"><slot name="sku"></slot></p>
    <p><slot name="actions"></slot></p>
  </template>

  <span slot="title">USB-C Camera</span>
  <span slot="price">$199</span>
  <span slot="sku">SKU: CAM-UC-01</span>
  <button slot="actions" type="button">Add to cart</button>
</product-card>

The product card declares an open shadow root containing its stylesheet and named slots. Light-DOM content fills those slots. Use shadowrootmode, not the older Chrome-only shadowroot attribute. section 9.6.1

Use this pattern when server rendering or static HTML should show styled component content before its module loads. For a component created entirely by JavaScript, attachShadow() is usually enough. Unlike an ordinary inert template, a declarative shadow root is live DOM: its external stylesheets and images can start loading during parsing. section 9.6.2 section 9.6.6

Keep hydration from undoing the early render:

  • Check for an existing root and reuse it; create one only as a fallback. Calling attachShadow() with a matching mode clears an existing declarative root, while a mismatched mode throws. section 9.6.3
  • Use attachInternals().shadowRoot when hydration must work with either open or closed declarative roots; this.shadowRoot exposes only open ones. section 9.6.3
  • Keep pre-upgrade content visible. If interaction must wait for registration, :not(:defined) can soften the appearance and disable a light-DOM button rather than hide the whole component. section 9.6.4

Optional template attributes mirror shadow-root options: shadowrootdelegatesfocus delegates focus, shadowrootclonable permits cloning or importing the root, and shadowrootserializable permits its inclusion through getHTML() with the appropriate option. Choose them for a concrete need, not by default. section 9.6.5

How Vanilla Web covers it

How deep it goes
Explains parsing, markup, hydration safeguards, resource loading, and optional attributes, while treating client-only attachShadow() as an alternative.
Examples
Uses a slotted product card, pre-upgrade CSS, a focus-delegating field, and cloning and serialization snippets.
What it assumes
Assumes familiarity with custom elements, templates, and shadow DOM, but defines the declarative parsing mechanism.
What you can do after
Build it from scratch in HTML, then hydrate without clearing the server-rendered shadow root.
How it connects
Connects shadow DOM to custom elements, server-side rendering, progressive enhancement, hydration, slots, and ElementInternals.

Also explained in

Compare how 2 books explain declarative shadow root →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vanilla Web. The section links point to the parts of the book it draws on.