Declarative Shadow DOM

Traditional Shadow DOM is created via JavaScript (attachShadow). For server-rendered pages, this means the shadow tree is empty until JS runs — defeating SSR's purpose of delivering complete HTML on first byte. Declarative Shadow DOM fixes this.

A <template> with shadowrootmode="open" declares a shadow root in HTML at parse time. The browser attaches the shadow root to the parent element automatically; the template's content becomes the shadow tree. No JavaScript required.

Declarative Shadow DOM enables true server-rendered web components: the server emits the full shadow tree inline, the browser parses and attaches it before any JS executes, and hydration JS can take over from a fully-rendered baseline. Equal footing with framework SSR.

Same modes as imperative attachShadow: shadowrootmode="open" exposes the shadow as element.shadowRoot; shadowrootmode="closed" hides it. Behavior is identical to the JavaScript-attached counterpart.

The browser attaches the shadow root the first time it sees the <template shadowrootmode>. Once attached, the template is consumed — querying for it later returns nothing. This matches the lifecycle of attachShadow: a shadow exists for the life of the element.

Light children (the <p> outside the <template> in the example) project into <slot> elements inside the shadow tree, just as with imperative shadow DOM. The composition story is identical; only the attachment mechanism differs.

If <my-card> is a registered custom element, the upgrade process picks up the already-attached shadow root rather than calling attachShadow again. The custom element class can read this.shadowRoot in its connectedCallback without needing to create it.

Lit-html's render, Astro components, and several other frameworks now emit declarative shadow DOM as part of their SSR output. Roll-your-own is feasible: any string-templating system can write the shadowrootmode template.

Declarative Shadow DOM ships in Chrome, Edge, Safari and Firefox. Older browsers ignore the <template> element silently — content inside the template is invisible, which is graceful degradation for non-supporting environments.

For broader support, a small script can walk the DOM and convert template[shadowrootmode] into actual shadow roots. Run before any custom element registration to ensure subsequent component upgrades see the expected shadow tree.

Declarative shadow DOM duplicates structure: the <template> content lives in the HTML even though it is also baked into the component's class. For pages with many of the same component, this inflates payload. Frameworks deduplicate; hand-rolled SSR may want to do the same.

If you ship web components and care about first-byte rendering or SEO — adopt now. The feature is stable, supported, and dramatically improves the SSR story for web-component-based applications. For non-shadow-DOM apps it does not apply.

What problem does Declarative Shadow DOM solve compared to imperative attachShadow?

Declarative Shadow DOM uses <template shadowrootmode="open"> inside a custom element to attach a shadow root at parse time, no JS required. Enables true SSR for web components: shadow tree, scoped styles, and slots all work before hydration. Supported in all modern browsers; polyfill available for older ones. Frameworks (Lit, Astro) emit it automatically.