Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 39 ยท Shadow DOM

Style Encapsulation in Shadow DOM

Understand how CSS is scoped in Shadow DOM, which styles still pass through, and how to style the host with :host, :host() and :host-context() and share stylesheets.

The headline feature of Shadow DOM is scoped CSS. A <style> inside a shadow root applies only to that root, and the page's selectors do not match elements inside it. This lesson covers exactly what is scoped, what still leaks through on purpose, how to style the host from the inside, and how to share one stylesheet between many components.

Scoping in both directions

Two rules summarize the behavior:

  1. Outside rules do not reach in. A page selector like p { color: red } does not match a <p> inside a shadow tree.
  2. Inside rules do not leak out. A <style> in a shadow root affects only that root's tree.
Scoped on both sides

Both worlds use the same class name tag and the same element selector p, and neither interferes with the other. This allows short, generic class names inside components.

What still passes through

Shadow DOM does not isolate absolutely. Three groups of styles flow into the shadow tree from the host.

Inherited properties. CSS properties that inherit by default (color, font-family, font-size, line-height, text-align, visibility, cursor, and so on) pass through the boundary just like they pass from a parent to a child. If the host sits in a red paragraph, text in the shadow tree is red unless the component sets its own color.

CSS custom properties. Variables like --accent are inherited too. This is the main way to theme a component from outside (the styling chapter develops it).

Parts and slotted content. The ::part() pseudo-element and ::slotted() also cross the boundary in controlled ways, covered later.

Inheritance and custom properties

The badge picks up the serif font and brown text color through inheritance, and its background through the --badge-bg variable. If you reset these in the component (for example :host { all: initial }), the component becomes fully isolated.

Styling the host: :host

The host element lives outside the shadow tree, so a normal selector cannot target it. Inside the shadow root, use :host:

CSS
:host {
  display: block;
  border: 1px solid #cbd5e1;
}

:host(selector)

Match the host only when it matches the selector inside the parentheses:

CSS
:host([disabled]) { opacity: .5; pointer-events: none; }
:host(.compact)   { padding: .25rem; }
:host(:hover)     { background: #f8fafc; }

:host-context(selector)

Match when the host or any of its ancestors matches the selector. It is handy for dark mode: :host-context(.dark) { ... }. :host-context() is only implemented in Chromium-based browsers (not in Firefox or Safari), so do not depend on it; prefer custom properties for theming.

:host rules

Important precedence rule: styles from the page win over :host rules. If the page writes alert-box { margin: 0 }, it overrides the margin from :host. That is a good thing: :host sets defaults that the page can adjust, so components are customizable without special hooks.

Sharing styles across components

A <style> string inside every component works but duplicates CSS in memory. Modern browsers support constructable stylesheets: create a CSSStyleSheet once and adopt it in many roots.

Constructable stylesheets

Updating shared later (for instance with shared.replaceSync(...)) restyles every component that adopted it at once. adoptedStyleSheets also works on document.

Another option is a <link rel="stylesheet" href="..."> inside the shadow root. The browser caches the file, though the first paint may flash unstyled content while it loads.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Does a page rule like p { color: red } style paragraphs inside a shadow root?

    Document styles are scoped to the document tree. Inherited properties still flow into the shadow tree, but selectors do not match inside.
  2. 2. Which values pass into a shadow tree from the host?

    Inherited properties such as color and font-family and custom properties such as --accent cross the boundary.
  3. 3. How do you style the host element from inside its shadow root?

    :host matches the shadow host from inside the shadow tree.
  4. 4. Who wins when the page and :host set the same property on the host?

    Outer (document) styles take precedence over :host rules, so :host provides adjustable defaults.

Summary

  • Selectors do not cross the shadow boundary in either direction.
  • Inherited properties and CSS custom properties do pass in; they are the theming channel.
  • Style the host with :host, :host(...) and, where supported, :host-context(...).
  • Page styles override :host defaults.
  • Share CSS between roots with constructable stylesheets and adoptedStyleSheets.

Next: Events and the Shadow Boundary