Declarative Shadow DOM 'shadowrootadoptedstylesheets'

at a glance

why it exists

Declarative Shadow DOM (DSD) lets you ship server-rendered shadow roots without JavaScript, but it has a stylesheet-sharing problem. When multiple shadow roots need the same CSS, authors must inline it inside every <template shadowrootmode="open">. A component used 100 times means 100 copies of the same styles in the HTML payload — inflating page weight and increasing both latency and memory use. The imperative equivalent (adoptedStyleSheets) solves this for JavaScript-instantiated shadow roots but can't help with DSD. Declarative CSS module scripts bridges the gap: define a stylesheet once in a <style type="module"> and reference it by name across any number of DSD instances.

shape of the API

Defining a named stylesheet

Use <style type="module"> with a module specifier to define an inline CSS module:

<!-- Define a reusable card stylesheet -->
<style type="module" specifier="card-styles">
  :host { display: block; border: 1px solid #ccc; padding: 1rem; }
  h2 { margin: 0 0 0.5rem; }
</style>

Referencing it from Declarative Shadow DOM

Use the shadowrootadoptedstylesheets attribute on a <template> tag to adopt the named module:

<my-card>
  <template shadowrootmode="open"
            shadowrootadoptedstylesheets="card-styles">
    <h2>Card Title</h2>
    <p>Card content here.</p>
  </template>
</my-card>

<my-card>
  <template shadowrootmode="open"
            shadowrootadoptedstylesheets="card-styles">
    <h2>Another Card</h2>
    <p>Same styles, one definition.</p>
  </template>
</my-card>

Multiple stylesheets

<style type="module" specifier="base">
  :host { box-sizing: border-box; }
</style>
<style type="module" specifier="theme">
  :host { color: var(--primary, #333); }
</style>

<my-widget>
  <template shadowrootmode="open"
            shadowrootadoptedstylesheets="base theme">
    <slot></slot>
  </template>
</my-widget>

Origin trial (historical, Chrome 148–153)

Before the feature shipped enabled by default in Chrome 153, an origin-trial token was required:

<meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE">

browser support

see also

• MSEdge Explainers — Declarative adopted stylesheets for shadow DOM
• WICG/webcomponents #939 — Declarative CSS module scripts discussion
• Chrome for Developers — Declarative Shadow DOM
• chromestatus — Declarative Shadow DOM 'shadowrootadoptedstylesheets' (4790543041298432)
• chrome-platform-showcase — live demo