Shadow DOM Encapsulation and Event Retargeting
Shadow DOM attaches an isolated DOM and CSS subtree to a host element. Outer stylesheets cannot pierce the boundary, light-DOM children project into <slot> placeholders, and composed DOM Events crossing outward have event.target rewritten to the host element.
Shadow Boundary Style Scoping & Event Retargeting
Trace how composed events retarget from an inner shadow button to the shadow host.
Inside shadowRoot, event.target is the internal <button> element.
// Inside shadowRoot: e.target === innerButton- phase
- AT_TARGET (shadow)
- eventTarget
- <button.save>
- composed
- true
Under the Hood
Blink attaches a ShadowRoot as an encapsulated subtree whose styles and IDs are scoped away from document selectors, then merges <slot> placeholders with light-DOM children in the flat tree for layout. When a composed event bubbles past the ShadowRoot boundary, the engine rewrites event.target to the host element.
- Flat Tree Composition: The layout engine merges
<slot>elements with slotted light-DOM children without moving nodes in the actual DOM. - Hard Style Boundary: Document selectors stop at the
ShadowRoot; only inheritable properties (color,font) and CSS custom properties cross inward, unlike CSS Cascade Layers. - Event Retargeting: Built-in UI events (
click,input) havecomposed: trueand retargete.targetto the host; custom events default tocomposed: falseand stop at the boundary.
<ui-badge>
<template shadowrootmode="open">
<style>:host { display: inline-flex; border: 1px solid; }</style>
<slot></slot>
</template>
Verified
</ui-badge>Problem Genealogy
- 2013 (Shadow DOM v0): Blink-only prototype with
/deep/and>>>combinators that leaked styles anyway. - 2016 (Shadow DOM v1): Removed piercing combinators, standardized
<slot>andattachShadow({ mode }). - 2024 (Declarative Shadow DOM):
<template shadowrootmode="open">enabled SSR without waiting for JS hydration.
Production Pitfalls
- Broken
for/aria-labelledbyIDs: ID references cannot crossShadowRootboundaries; keep labels and inputs in the same tree, and attach any MutationObserver directly to the shadow root if you need to observe internal changes. - Lost Design-System Typography: Global CSS resets (
button { font: inherit }) do not enter shadow trees; share tokens via CSS custom properties or constructableadoptedStyleSheets.
- When not to use Shadow DOM: Never wrap ordinary application pages or forms in Shadow DOM, it breaks global form submission, accessibility IDs, and utility CSS unless paired with
ElementInternals.
Connections & Logical Next Steps
Custom elements typically attach a ShadowRoot in constructor() and hydrate slots in connectedCallback().
Shadow DOM provides style and DOM tree scoping without allocating a separate browsing context.
Shadow trees modify event propagation by retargeting event.target to the host at the ShadowRoot.
Cascade Layers organize light-DOM specificity; Shadow DOM creates a hard selector boundary.
Outer MutationObserver instances stop at the ShadowRoot boundary unless attached inside the shadow tree.
Mechanical Comparisons
Cascade Layers organize light-DOM specificity; Shadow DOM creates a hard selector boundary.
Outer MutationObserver instances stop at the ShadowRoot boundary unless attached inside the shadow tree.