Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 39 ยท Shadow DOM

Shadow DOM Basics

Learn what Shadow DOM is, how attachShadow creates a shadow root, which elements can host one, and how the shadow tree differs from the light DOM and the page.

Every web page has one big document tree, and every script and style sheet can reach everything in it. That is convenient for pages but dangerous for components: a stray div { margin: 0 } or document.querySelector("button") can break a widget it knows nothing about. Shadow DOM solves this by letting an element own a separate, hidden subtree whose boundary protects it from the outside, and protects the outside from it.

Key vocabulary

Shadow DOM vocabulary

Shadow host The element that owns a shadow tree
Shadow root The root node of that private tree
Shadow boundary Where the private tree meets the page

Everything between host and boundary is the component's own world.

1 / 2
  • The shadow host is the ordinary element (a custom element, a <div>, ...) that has the shadow tree attached.
  • The shadow root is the ShadowRoot node, a special DocumentFragment, at the top of the shadow tree.
  • The light DOM is the host's regular children, the ones you write in HTML.
  • The flat tree is what the browser renders after it combines the shadow tree with slotted light DOM (slots come in chapter 4).

Creating a shadow root

You call attachShadow on an element and pass an options object:

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

attachShadow returns the new ShadowRoot. You can attach only one shadow root per element; a second call throws a NotSupportedError. The mode option is required and is either "open" or "closed" (next lesson).

Two worlds, one element

The host's own text (light DOM) appears through the <slot> that the shadow tree provides. If the shadow root had no slot, the light DOM would be hidden, because the browser renders the shadow tree instead of the host's children. The page's red p rule never reaches the teal paragraph.

Which elements can host a shadow root?

All autonomous custom elements, plus this fixed list of built-ins: article, aside, blockquote, body, div, footer, h1 to h6, header, main, nav, p, section, span. Form controls and replaced elements such as input, button, img, textarea, select, a and video cannot host one, because they already have their own internal (user-agent) shadow tree.

JavaScript
document.createElement("button").attachShadow({ mode: "open" }); // NotSupportedError

Querying across the boundary

The boundary is enforced by the DOM APIs:

Expression Sees into the shadow tree?
document.querySelector(...) No
host.querySelector(...) No (searches only the light DOM)
host.shadowRoot.querySelector(...) Yes (if the root is open)
host.children, host.innerHTML Light DOM only
host.shadowRoot.innerHTML The shadow tree

This is why components use this.shadowRoot.querySelector for internal lookups. It is also why test code and page scripts do not accidentally break a widget.

Why it matters: protection both ways

Shadow DOM gives you three kinds of isolation:

  1. DOM isolation: outside selectors and getElementById do not find shadow nodes, so IDs inside a component never clash with page IDs.
  2. Style isolation: outside rules do not match inside, and inside rules do not leak out (the next lessons show exceptions that are inherited properties and custom properties).
  3. Event isolation: events are retargeted at the boundary so outsiders see the host, not the internals (lesson 4 of this chapter).
Duplicate ids are fine

Three id="title" elements exist in three separate trees and nothing breaks. This frees component authors to use short, readable ids and classes.

What Shadow DOM does not do

  • It is not a security boundary. An open shadow root is reachable through host.shadowRoot, and even a closed one is reachable by anyone who controls the page's script. It prevents accidents, not attacks.
  • It does not isolate JavaScript. Scripts share one global scope.
  • It does not isolate everything in CSS. Inherited properties (color, font-family, line-height) and CSS custom properties pass into the shadow tree, so a component can still pick up site typography and theme colors. That is a feature and is the subject of the styling chapter.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the shadow host?

    The host is the ordinary element that owns the shadow tree; the shadow root is the tree's top node.
  2. 2. How many shadow roots can one element have?

    A second attachShadow call on the same element throws a NotSupportedError.
  3. 3. Which of these can NOT host a shadow root?

    Form controls such as button already have a built-in shadow tree and cannot take another.
  4. 4. What happens to a host's light DOM children if the shadow tree has no slot?

    Without a slot, nothing in the shadow tree shows the light DOM, so it stays in the DOM but is not rendered.

Summary

  • Shadow DOM gives an element a private subtree with a protective boundary.
  • Use host.attachShadow({ mode }) once per element; it returns the ShadowRoot.
  • Light DOM is what you write inside the tag; the flat tree combines both for rendering.
  • Document-level queries and selectors do not cross the boundary; ids can repeat safely.
  • It prevents accidents but is not a security feature, and inherited styles still pass through.

Next: Open and Closed Shadow Roots