JavaScript Reference ยท DOM: Document and Elements
Shadow DOM
Reference for shadow DOM: attachShadow(), open and closed modes, style encapsulation, slots, host styling, event retargeting and declarative shadow roots.
Shadow DOM gives an element its own private DOM tree, the shadow root, whose elements and styles are separated from the rest of the page. CSS inside the shadow tree does not leak out, and page CSS does not reach in (apart from inherited properties and the hooks you expose). This is how a widget can keep its internals safe from the surrounding page.
Browsers use it themselves: the controls of <video> and <input type="range"> are built in shadow trees.
const host = document.querySelector("#host"); const root = host.attachShadow({ mode: "open" }); root.innerHTML = "<p>Hidden from page CSS</p>";
Try it
Syntax
const shadowRoot = element.attachShadow(init); element.shadowRoot // the root, or null if closed or absent
<div> <template shadowrootmode="open">...</template> </div>
Parameters
| Name | Description |
|---|---|
init.mode |
"open" exposes the root as element.shadowRoot; "closed" returns it only from attachShadow(). |
init.delegatesFocus |
If true, clicking non-focusable parts of the shadow tree focuses the first focusable element inside. |
init.slotAssignment |
"named" (default) or "manual". |
init.clonable / init.serializable |
Newer options for cloning and serializing the shadow root. |
Return value and exceptions
attachShadow() returns the ShadowRoot. It throws NotSupportedError if the element cannot host a shadow root (for example <input>) or already has one.
CSS hooks
| Selector or feature | Description |
|---|---|
:host, :host(.class) |
Selects the host element from inside. |
::slotted(selector) |
Styles light DOM nodes assigned to a slot (top-level only). |
::part(name) |
Lets the page style elements marked with part="name" in the shadow tree. |
| CSS custom properties | Inherit into shadow trees, so they are the simplest theming channel. |
Usage notes
- Closed mode is not security. It only hides the reference; it cannot protect secrets, and other code can often reach the content in other ways. Use
openunless you have a specific reason. - Queries stop at the boundary.
document.querySelector()does not look into shadow roots. Queryelement.shadowRootinstead. - Event retargeting. Events that cross the boundary appear to come from the host. Use
event.composedPath()for the real path. Events withcomposed: false, such as many custom events by default, do not leave the shadow tree. - Slots project light DOM. Children of the host stay in the page tree and keep the page's styles; the slot only decides where they are displayed.
- IDs are scoped. Duplicate ids inside and outside a shadow tree do not clash. Labels and ARIA references (
for,aria-labelledby) cannot cross the boundary. - Inherited styles still flow in:
color,font-familyand other inherited properties pass through the host. - Server rendering: declarative shadow DOM (
<template shadowrootmode>) lets HTML create a shadow root without scripts. - Form controls. Inputs inside a shadow root do not participate in an outer
<form>; use form-associated custom elements to forward values.
Browser support
Shadow DOM with attachShadow() is supported in all current browsers. Declarative shadow DOM and options such as clonable and serializable are more recent, so check a compatibility table.