Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
const host = document.querySelector("#host");
const root = host.attachShadow({ mode: "open" });
root.innerHTML = "<p>Hidden from page CSS</p>";

Try it

Style encapsulation
Slots and host styling

Syntax

JavaScript
const shadowRoot = element.attachShadow(init);
element.shadowRoot        // the root, or null if closed or absent
HTML
<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 open unless you have a specific reason.
  • Queries stop at the boundary. document.querySelector() does not look into shadow roots. Query element.shadowRoot instead.
  • Event retargeting. Events that cross the boundary appear to come from the host. Use event.composedPath() for the real path. Events with composed: 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-family and 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.