Draft:Shadow DOM

Shadow DOM is a web platform feature that enables hidden DOM subtrees, known as shadow trees, to be attached to elements in a document, providing encapsulation of structure and styling from the rest of the page. It originated as part of the Web Components initiative alongside technologies such as Custom Elements and the HTML template element, and is now specified within the DOM and HTML standards. All major modern browsers implement the standardized "v1" Shadow DOM API, while the earlier "v0" API has been deprecated and removed.

Definition

A shadow tree is a separate node tree rooted at a shadow root, which is attached to a shadow host: an element in the regular document tree. The shadow host renders according to its shadow tree, while remaining part of the document's own DOM. The point where the two trees meet is called the shadow boundary, which enforces encapsulation: neither styles nor JavaScript from the outer document can reach inside the shadow tree unless explicitly permitted.

Background and history

Shadow DOM traces its origins to discussions in 2010–2011 among Google engineers and other contributors on W3C public mailing lists, where ideas for DOM encapsulation were first explored. An initial "v0" specification, published as a W3C Working Draft in 2013, introduced features including multiple shadow trees per host element and a <content> element for content projection. Google shipped v0 in Chrome alongside Custom Elements v0 and HTML Imports, but other browser vendors did not follow.

Apple's WebKit team raised concerns about the complexity of v0 and proposed a simpler, slot-based API. The resulting "v1" design removed multiple shadow roots per host, replaced <content> with <slot>, and clarified encapsulation semantics. Safari and Chrome shipped v1 support in the mid-2010s, followed by Firefox in 2018. Chrome subsequently deprecated and removed v0 along with HTML Imports in 2019.

Relationship to Web Components

Shadow DOM is one of three core technologies in the Web Components suite, alongside Custom Elements and the HTML template element. Together they enable creation of reusable, encapsulated components that combine markup, style, and behavior without depending on external libraries. Shadow trees allow such components to render internal structure without exposing it as part of the page's main DOM.

Shadow-like mechanisms have long been used internally by browsers to implement complex built-in elements. Elements such as <video>...</video> and <details>...</details> render their controls through internal shadow trees while presenting a simple interface in the light DOM — standardized Shadow DOM extends the same capability to author-defined elements.

Concepts and terminology

Shadow tree and shadow root

A shadow tree is a node tree whose root is a shadow root, attached to a host element in another tree. The shadow root itself is not part of the regular document DOM; it exists as a separate tree accessible only through the host element's shadowRoot property (in open mode) or not at all (in closed mode). Each element may have at most one shadow root — earlier v0 drafts permitted multiple shadow trees per host, but v1 removed this in favour of simpler slot-based composition.

Host element and light DOM

The element to which a shadow root is attached is called the shadow host. The host remains part of the light DOM — the regular document tree — while its rendering is determined by the shadow tree. The host's own children in the light DOM are not rendered by default; instead they can be projected into the shadow tree through slots.

Slots and content projection

In Shadow DOM v1, the <slot>...</slot> element serves as a placeholder inside a shadow tree into which children from the host's light DOM are projected. Slots can be unnamed (the default slot) or named via a name attribute; light DOM children target a specific slot by setting a matching slot attribute. Unassigned children fall through to the default slot.

This mechanism replaced the <content>...</content> element from v0, which used CSS selectors to determine which light DOM nodes appeared at a given insertion point. The switch to <slot>...</slot> was part of the v1 redesign agreed between browser vendors to simplify the specification and better support component subclassing.

Technical overview

Attaching a shadow root

A shadow root is created by calling attachShadow() on an element, passing an options object with a mode property. A call of the form element.attachShadow({mode: 'open'}) returns a reference to the new shadow root, after which child nodes, attributes, and styles can be appended to it using standard DOM APIs.

In practice, authors typically call attachShadow() inside a custom element constructor and populate the shadow tree by cloning the contents of an <template>...</template> element. The <template> element's content is inert until instantiated — its content property exposes a DocumentFragment that can be inserted directly into the shadow tree.

Encapsulation and CSS scoping

Styles defined inside a shadow tree are scoped to that tree and do not leak outward; selectors from the outer document do not match elements inside the shadow tree. Two CSS integration points allow controlled styling across the boundary: the :host pseudo-class styles the host element from within its own shadow tree, while the ::slotted() pseudo-element targets top-level slotted content. The behaviour of these selectors is defined in the CSS Scoping Module Level 1.

Open and closed shadow roots

The mode option passed to attachShadow() determines whether the shadow root is open or closed. In open mode the host's shadowRoot property returns the shadow root, allowing external scripts to traverse the tree. In closed mode shadowRoot returns null, and the component retains access only through a private reference kept internally.

Closed mode is intended as an encapsulation convenience — discouraging external code from depending on internal details — rather than a security boundary. Various DOM APIs and browser extension mechanisms can still expose or influence shadow content regardless of mode.

Declarative Shadow DOM

Declarative Shadow DOM allows shadow roots to be defined directly in HTML markup without JavaScript. A <template>...</template> element with a shadowrootmode attribute placed inside a host element causes the browser to attach a shadow root during HTML parsing, moving the template's children into the shadow tree and removing the template from the DOM.

The feature is primarily aimed at server-side rendering of web components and environments where JavaScript may be unavailable or restricted. By constructing shadow trees during parsing rather than at runtime, it can reduce layout shifting and improve metrics such as Largest Contentful Paint.

Browser support and standardization

The W3C published a Shadow DOM Recommendation in 2018, with its content subsequently incorporated into the WHATWG DOM Living Standard, the HTML specification, CSS Scoping Module Level 1, and the UI Events specification. The WHATWG DOM Standard now defines shadow trees, shadow roots, and event dispatch across shadow boundaries as part of the living standard.

Chrome shipped Shadow DOM v1 in version 53 (2016), Safari followed later that year, and Firefox added support in 2018. Microsoft Edge gained support through its transition to the Chromium engine. Chrome deprecated and removed Shadow DOM v0, Custom Elements v0, and HTML Imports in 2019 after a transition period during which both APIs were available simultaneously.

Declarative Shadow DOM has shipped in Chromium-based browsers and Safari, with ongoing work to align the HTML specification with the declarative model.

Use cases

Browsers have long used internal shadow trees to implement built-in user interface elements such as form controls and media players, hiding implementation details from the page DOM. Standardized Shadow DOM extends this capability to author-defined components, enabling custom elements that expose a simple API while keeping internal markup and styles encapsulated.

Developers commonly use Shadow DOM when building design systems, reusable UI widgets, and embeddable components that must coexist with arbitrary host pages without CSS collisions. Declarative Shadow DOM extends these patterns to server-rendered environments, allowing components to arrive fully structured from the server without depending on client-side JavaScript.

Advantages

Shadow DOM's style scoping allows authors to reuse common class names inside different components without risking conflicts with global stylesheets, and reduces dependence on deeply nested selectors. Components can manage their own DOM and CSS independently, which can improve maintainability in large applications composed of many widgets.

Limitations and criticism

Shadow DOM v0 attracted criticism for complexity and for aspects of its encapsulation model that made subclassing difficult, which contributed to its limited adoption outside Chrome and motivated the v1 redesign.

The v1 API introduces additional complexity for tooling and debugging, particularly in applications that combine Web Components with existing frameworks or rely on global CSS. Accessibility specialists have noted that encapsulation can make it harder to inspect semantics and test the composed accessibility tree, requiring deliberate attention to WAI-ARIA roles and keyboard navigation across shadow boundaries. Form participation is also not automatic — inputs inside a shadow tree do not submit their values with a containing light DOM form by default, and form validation states are not propagated across the shadow boundary.

Accessibility

The Shadow DOM specification states that user agents traverse the document as rendered, meaning WAI-ARIA roles and properties inside shadow trees are exposed to assistive technologies as part of the composed tree. Authors must nonetheless ensure correct semantics, labeling, and focus management, and should test keyboard navigation and screen reader behavior against the composed DOM rather than the shadow tree in isolation.

Security considerations

Shadow DOM is a tool for DOM composition and encapsulation, not a security boundary. The host element's shadowRoot property in open mode, along with various other DOM APIs, can expose shadow tree contents to scripts on the page. Robust isolation requires mechanisms such as the same-origin policy, Content Security Policy, or <iframe>...</iframe> sandboxing rather than Shadow DOM alone.

Relationship to frameworks

Shadow DOM serves as a standardized component boundary that many frameworks and libraries interoperate with, even when using their own internal rendering strategies. Frameworks such as Polymer built directly on top of Shadow DOM and its polyfills, using the terms local DOM for a component's shadow tree and light DOM for its externally managed children — terminology that aligns with the platform specifications.

Examples

A basic custom element using Shadow DOM typically follows this pattern: a class extending HTMLElement calls this.attachShadow({mode: 'open'}) in its constructor, then appends a <style>...</style> element and markup to the returned shadow root. Named slots can be included in the shadow tree to accept specific light DOM children by their slot attribute.

With Declarative Shadow DOM, the same structure can be expressed in plain HTML: a <template>...</template> element with shadowrootmode="open" nested inside the host element defines the shadow tree at parse time, enabling fully structured server-rendered components without client-side JavaScript.

See also

• Web Components
• Custom Elements
• HTML template element
• Document Object Model
• CSS Scoping Module Level 1
• Largest Contentful Paint
• WAI-ARIA