Shadow DOM

Shadow DOM is a browser feature that allows websites to define self-contained HTML elements on the website. These self-contained elements, called shadow trees, allow website developers to bundle together related HTML markup and CSS styling in a manner such that the styling and code does not affect other surrounding elements. This solves a recurring problem that web developers face of unintended interference between components, where CSS rules written for one part of a page can accidentally affect unrelated parts of the website.

The shadow DOM feature originated as part of the Web Components initiative by Google alongside other proposals like Custom Elements and the HTML template element in 2013. After criticism from Apple and Mozilla on the first version of the Shadow DOM proposal, called the "v0" design, a new proposal called the "v1" design was published and was subsequently adopted by all major web browsers.

History

Shadow DOM traces its origins to discussions between 2010 and 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. Mozilla's Firefox team aligned with the WebKit team on opposing many implementation details of the v0 API. Disagreements between browser vendors on the shape and implementation of the API led to a "face-to-face" meeting of the W3C Web Applications Working Group at Mountain View in April 2015. Discussion following the meeting resulted in the browser vendors agreeing on a "v1" design which removed multiple shadow roots per host, replaced <content> with <slot>, and shifted towards a more declarative API. In 2018, W3C published a Working Group Note that the new version of the Shadow DOM API would be incorporated into various web specifications instead of being published through Working Drafts. 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 in version 79, in which it transitioned to the Chromium engine. Chrome deprecated and removed Shadow DOM v0, Custom Elements v0, and HTML Imports in 2019. A new addition to the specifications, declarative Shadow DOM has shipped in Chromium-based browsers and Safari as of 2024.

Overview

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 natively on the web. 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. Shadow DOM extends the same capability to developer-defined elements.

The Shadow DOM consists of multiple shadow trees which are HTML DOM trees whose root is called a shadow root, attached to an element called the host element in the normal DOM tree of the page of a website. 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). Earlier v0 drafts permitted multiple shadow trees per host, but v1 removed this in favour of simpler slot-based composition that only allows one shadow tree per host. Elements outside the shadow DOM are called the light DOM.

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 or populate the shadow tree by cloning the contents of an <template>...</template> element. The <template> element's content is inert until instantiated. The template element exposes a content property which exposes a DocumentFragment that can be inserted directly into the shadow tree.

Features

Encapsulation

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 DOM elements inside slots. 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 discouraging traversal.

Content projection

Shadow DOM defines elements serves as a placeholder inside a shadow tree into which children from the host's light DOM are placed. This is called content projection. In the v1 specification this is typically done through <slot>...</slot> elements. 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.

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.

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 can 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.

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 by decreasing naming collisions and unexpected cascading behavior in large applications composed of many widgets. This has led to JavaScript frameworks adopting Shadow DOM as a component boundary. Frameworks like Polymer and it's successor Lit are built directly on top of Shadow DOM and its polyfills, use the terms local DOM for a component's shadow tree and light DOM, to describe elements managed by the framework. Other frameworks like Angular, Vue and Svelte support using the Shadow DOM API to encapsulate styles inside their components.

Limitations

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. 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.

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.