JavaScript Element attachShadow() Method

What You’ll Learn

Element.attachShadow() is an instance method that attaches a Shadow DOM tree to a host element and returns a ShadowRoot. Learn open vs closed mode, custom elements, slots, and five try-it labs.

Introduction

Normal DOM children are part of the page’s main tree. A shadow tree is a separate DOM attached to a host element. Styles and markup inside the shadow root stay encapsulated—ideal for reusable components.

attachShadow() is the JavaScript way to create that root (you can also create one declaratively with the shadowrootmode attribute). It is the foundation of many custom elements.

This page is part of JavaScript Element. Related topics include shadowRoot and append().

Understanding the attachShadow() Method

Calling el.attachShadow(options) makes el a shadow host and returns the new ShadowRoot. You then append nodes (or set innerHTML) on that root.

• It is an instance method on Element.
• mode controls whether el.shadowRoot stays readable.
• Not every tag can host a shadow root (security / platform limits).
• Calling again on an existing programmatic shadow root usually throws.
• Optional flags: delegatesFocus, slotAssignment, clonable, serializable, and more.

📝 Syntax

General form of Element.attachShadow (MDN):

attachShadow(options)

Parameters

options — an object that includes:

• mode (required) — "open" (readable via element.shadowRoot) or "closed" (shadowRoot is null).
• clonable (optional) — include the shadow root when cloning the host (default false).
• delegatesFocus (optional) — focus the first focusable part when clicking non-focusable shadow content (default false).
• slotAssignment (optional) — "named" (default, automatic slots) or "manual" (HTMLSlotElement.assign()).
• serializable (optional) — allow serialization via getHTML() options (default false).
• customElementRegistry (optional) — scoped registry for the shadow root.
• referenceTarget (optional) — ID of an inner element that becomes the effective target of external references to the host.

Return value

Returns a ShadowRoot object.

Exceptions

MDN: may throw when attaching to an unsupported element, when shadow is disabled via custom element disabledFeatures, when a conflicting shadow root already exists, when declarative mode mismatches, or when an invalid customElementRegistry is passed.

Common patterns

const host = document.querySelector("#host");
const shadow = host.attachShadow({ mode: "open" });
shadow.innerHTML = "
Inside the shadow tree
";

// Later (open mode only):
host.shadowRoot.querySelector("p");

const closed = host2.attachShadow({ mode: "closed" });
host2.shadowRoot; // null — keep `closed` yourself

Examples Gallery

Examples follow MDN Element.attachShadow() patterns. Use View Output or Try It Yourself for each case.

const host = document.getElementById("host");
const shadow = host.attachShadow({ mode: "open" });

const p = document.createElement("p");
p.textContent = "Hello from the shadow DOM";
shadow.appendChild(p);

console.log(host.shadowRoot === shadow); // true

true
Hello from the shadow DOM

const host = document.getElementById("host");
const shadow = host.attachShadow({ mode: "closed" });

shadow.innerHTML = "Secret internals";

console.log(host.shadowRoot); // null
console.log(shadow.querySelector("span").textContent);
// "Secret internals" — only via the saved reference

null
Secret internals

class HelloCard extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: "open" });
    shadow.innerHTML = `
      
      Hello, custom element!
    `;
  }
}

customElements.define("hello-card", HelloCard);

Hello, custom element!

class MyArticle extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "open" /* named is default */ });
  }
  connectedCallback() {
    this.shadowRoot.innerHTML = `
      

      

    `;
  }
}
customElements.define("my-article", MyArticle);

// Light DOM:
// <my-article>
//   <span slot="title">Title text</span>
//   <p>Body goes to default slot</p>
// </my-article>

Title text
Body goes to default slot

const host = document.getElementById("host");
host.attachShadow({ mode: "open" }).innerHTML =
  'Click me';

const btn = host.shadowRoot.getElementById("go");
btn.addEventListener("click", () => {
  console.log("Clicked inside shadow");
});

console.log(host.shadowRoot.mode); // "open"

open
(click the shadow button — logs: Clicked inside shadow)

🚀 Common Use Cases

• Building custom elements with encapsulated markup and CSS.
• Hiding internal structure from global page styles.
• Projecting light DOM into slots for flexible component APIs.
• Pairing with declarative shadow DOM for SSR / progressive enhancement.
• Teaching open vs closed encapsulation for beginners.
• Focus-friendly widgets with delegatesFocus: true.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available since January 2020).
• Some options (slotAssignment: "manual", serializable, scoped registries) may have narrower support—check compatibility.
• Custom elements can disable shadow via static disabledFeatures = ["shadow"].
• Declarative shadow DOM uses shadowrootmode on a <template>.
• Related: shadowRoot, slot, append(), JavaScript hub.

💡 Best Practices