v148 · CSS · Web Components

Declarative CSS module scripts

Define inline CSS style modules with <style type="module" specifier="foo"> and apply them to declarative shadow roots via shadowrootadoptedstylesheets="foo" — sharing stylesheets across shadow DOMs without JavaScript or FOUC-prone <link> elements.

concepts

  1. Style Module Share

    A single inline <style type="module"> block shared by multiple custom elements via shadowrootadoptedstylesheets — update the shared module once, all components reflect the change.

  2. Shadow DOM Theming

    A design-token style module referenced by a family of components. Toggle themes by swapping which specifier each shadow root adopts — without re-rendering or using CSS custom properties inheritance.

  3. Component Library

    A small component library — cards, buttons, badges — built entirely with declarative CSS module scripts. Four modules defined once in <style type="module" specifier="…"> blocks are adopted by multiple custom elements, demonstrating real-world stylesheet sharing with no JavaScript import boilerplate.

  4. CSS Module Playground

    A live editor comparing three ways to style shadow DOM: dynamic CSSStyleSheet construction, JS import assertions, and the new declarative approach. Edit CSS live and watch shadow roots update. A "share module" section shows one sheet adopted by three independent shadow roots simultaneously.

  5. Style Isolation Demo

    Compare CSS modules (one shared CSSStyleSheet object, parsed once) versus inline <style> tags (separate parse per component). A memory chart lets you slide the component count from 1 to 500 to see how stylesheet memory cost scales linearly with duplicates but stays flat with modules.

why it shipped

"Styling and Customization" is consistently ranked the #1 pain point for Web Components developers. The core problem: shadow DOM encapsulation blocks style inheritance, so sharing styles between components requires JavaScript (CSSStyleSheet + adoptedStyleSheets), external CSS files (risking FOUC), or duplicating <style> blocks. Declarative CSS Module Scripts close the gap by letting HTML alone define and apply shared stylesheets — the same encapsulation model, but declaratively, with no script and no flash. The feature entered origin trial in Chrome 148.

references

implementation reference

Need the exact API surface, compatibility boundaries, errors, lifecycle, and source links? Read the matching gendn reference ↗