liveBook · Manning

Declarative shadow root

As explained in Web Component Development with Modern Libraries and Tooling

Declarative Shadow DOM is a browser feature that declares a shadow DOM tree in HTML markup for parser-based attachment.

Declarative Shadow DOM (DSD) lets an HTML response provide a web component’s shadow content before its JavaScript runs. This makes server-side rendering possible for web components: visitors can receive populated custom elements instead of waiting for browser-side code to add their initial content. section 11.0 section 11.2

A greeting rendered by the server

The server can return `<hello-world name="SSR"><template shadowrootmode="open"><style>:host { color: blue; }</style><p>Hello, SSR!</p></template></hello-world>`. The template holds the initial styling and greeting. Its `shadowrootmode` attribute tells the browser to create a shadow root for the custom element; inspecting the result shows the paragraph and style inside that root. section 11.2

For a component that also renders on the client, share a function that generates its inner HTML. The server places that HTML inside the declarative template. In the component constructor, check `this.shadowRoot`: if it already exists, keep it; otherwise call `attachShadow` and populate it for client-side rendering. The component can then add behavior to the existing content. section 11.2

Two practical distinctions matter:

  • DSD supplies initial content; interactive behavior can still be attached by client-side code. A server-rendered radio group, for example, gains a change listener after it is inserted. section 11.3
  • HTML assigned with `innerHTML` does not activate declarative shadow roots. For that insertion path, `setHTMLUnsafe(htmlString)` triggers DSD parsing, but support for this method only became complete in September 2025. section 11.4
  • With Lit, client hydration support reuses existing DSD roots; without that import, the example renders the DSD content twice. section 11.4
Listing 11.2 public/hello-world-html.js ssr function
export function ssr(name) {
  const attr = name ? `name="${name}"` : "";
  return html`
    <hello-world ${attr}>
      <template shadowrootmode="open">${content(name)}</template>
    </hello-world>
  `;
}

See how the vanilla SSR function wraps shared component content in `<template shadowrootmode="open">`. section 11.2

Use DSD when a web component needs server-rendered initial content, particularly when initial rendering performance or search visibility matters. It works with vanilla components and has support in Lit, Stencil, FAST, and wrec; SSR is not necessarily worthwhile for every application. section 11.0 section 11.8

How Web Component Development with Modern Libraries and Tooling covers it

How deep it goes
Works through vanilla SSR markup, client-side reuse, dynamic insertion behavior, and Lit hydration.
Examples
Uses server-rendered greeting and radio-group components, plus a Lit example that hydrates existing shadow roots.
What it assumes
Assumes basic HTML and JavaScript while walking through a vanilla custom element and its server-generated markup.
What you can do after
Build it from scratch with a declarative template and a custom-element constructor that preserves an existing shadow root.
How it connects
Connects custom elements, shadow DOM, HTML templates, server-side rendering, client-side rendering, and hydration.

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 Web Component Development with Modern Libraries and Tooling. The section links point to the parts of the book it draws on.