How it works
A shadow root is a DocumentFragment whose host is an element. The document tree and each shadow tree are separate node trees; the browser renders the flat tree, in which the host's shadow tree replaces its children and each <slot> is replaced by the light-DOM nodes assigned to it. Selectors match within one tree, which is why encapsulation holds both ways, while inheritance follows the flat tree: a shadow tree's top-level elements inherit from the host, and slotted elements inherit from their slot.
Cascade. CSS Cascade 5 adds context as a sort criterion, after origin and importance and before inline styles, layers and specificity. For normal declarations the outer tree wins; for !important the inner tree wins. So a component's :host { padding: 10px } is a default the page can override with x-card { padding: 3px }, while :host { padding: 10px !important } beats even a page rule marked !important. Chrome 156 and Firefox 159 resolved both cases that way.
Shadow selectors:
:host matches the host from inside its shadow tree, :host(.compact) only when the host matches .compact.
:host-context(.dark) matches when the host or any shadow-including ancestor matches. Only Chromium supports it: Firefox 159 rejects it as invalid, and MDN's data lists no Safari support. Use a custom property or a host attribute instead.
::slotted(<compound>) matches top-level slotted elements only (see templates and slots).
::part(name) matches elements with that part from outside, can be followed by state pseudo-classes and pseudo-elements, but not by combinators.
Events. Dispatch builds the event path with each target's get the parent: a shadow root's parent is its host unless the event isn't composed and the root is where the event started. So non-composed events end at the shadow root. For each listener, the browser retargets event.target against the listener's tree: it walks up from the real target, replacing it with the host of each shadow root the listener can't see into.
// <x-box> with a shadow root containing <button id="b">
const button = root.getElementById('b');
document.addEventListener('ping', (e) => console.log('document', e.target.localName));
root.addEventListener('ping', (e) => console.log('root', e.target.id));
button.dispatchEvent(new CustomEvent('ping', { bubbles: true }));
// → root b
button.dispatchEvent(new CustomEvent('ping', { bubbles: true, composed: true }));
// → root b
// → document x-box
focus and blur are composed but don't bubble: a capturing listener on document sees focus with target the host, and a listener on the host runs because the retargeted event is at its target there. focusin and focusout are composed and bubble.
Edge cases
- Closed roots in
composedPath(). For a listener outside, nodes inside a closed shadow root are left out: the path starts at the host. With an open root the path starts at the inner node.
- One root per element. Calling
attachShadow() again throws NotSupportedError, except on a declarative shadow root of the same mode (see declarative shadow DOM).
- IDs and ARIA. Id references (
for, aria-labelledby, aria-describedby) don't cross the boundary in either direction, which is an accessibility problem for form controls inside components.
- Shared styles.
root.adoptedStyleSheets = [sheet] with a constructed CSSStyleSheet shares one parsed sheet across every instance instead of a <style> per shadow root.
Real-world scenario
A design system ships <ds-button> used by apps with their own CSS. The app's resets can't break the button's internals, but the app still needs theming. The component exposes custom properties (--ds-button-bg) for colours and spacing, part="label" for the rare structural override, and documents both as its public styling API. Anything else is internal and can change without breaking consumers.
Trade-offs
- Isolation vs reuse. Utility CSS and global typography don't apply inside, so components either duplicate them, adopt shared sheets, or rely on inherited properties.
- Open vs closed. Open roots let tests, devtools extensions and integrations inspect the component; closed roots buy little. Most libraries use
open.
- Shadow DOM vs light DOM. Some components skip shadow DOM to keep page styles and id references working, accepting that their markup is unprotected.