W3cubDocs

/Web APIs

Element: attachShadow() method

The Element.attachShadow() method attaches a shadow DOM tree to the specified element and returns a reference to its ShadowRoot.

Elements you can attach a shadow to

Note that you can't attach a shadow root to every type of element. There are some that can't have a shadow DOM for security reasons (for example <a>).

The following is a list of elements you can attach a shadow root to:

Syntax

js

attachShadow(options)

Parameters

options

An object which contains the following fields:

mode

A string specifying the encapsulation mode for the shadow DOM tree. This can be one of:

open

Elements of the shadow root are accessible from JavaScript outside the root, for example using Element.shadowRoot:

js

element.attachShadow({ mode: "open" });
element.shadowRoot; // Returns a ShadowRoot obj
closed

Denies access to the node(s) of a closed shadow root from JavaScript outside it:

js

element.attachShadow({ mode: "closed" });
element.shadowRoot; // Returns null
delegatesFocus Optional

A boolean that, when set to true, specifies behavior that mitigates custom element issues around focusability. When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available :focus styling. Its default value is false.

slotAssignment Optional

A string specifying the slot assignment mode for the shadow DOM tree. This can be one of:

named

Elements are automatically assigned to <slot> elements within this shadow root. Any descendants of the host with a slot attribute which matches the name attribute of a <slot> within this shadow root will be assigned to that slot. Any top-level children of the host with no slot attribute will be assigned to a <slot> with no name attribute (the "default slot") if one is present.

manual

Elements are not automatically assigned to <slot> elements. Instead, they must be manually assigned with HTMLSlotElement.assign(). Its default value is named.

Return value

Returns a ShadowRoot object.

Exceptions

InvalidStateError DOMException

The element you are trying to attach to is already a shadow host.

NotSupportedError DOMException

You are trying to attach a shadow root to an element outside the HTML namespace, the element cannot have a shadow attached to it, or the static property disabledFeatures has been given a value of "shadow" in the element definition.

Examples

The following example is taken from our word-count-web-component demo (see it live also). You can see that we use attachShadow() in the middle of the code to create a shadow root, which we then attach our custom element's contents to.

js

// Create a class for the element
class WordCount extends HTMLParagraphElement {
  constructor() {
    // Always call super first in constructor
    super();

    // count words in element's parent element
    const wcParent = this.parentNode;

    function countWords(node) {
      const text = node.innerText || node.textContent;
      return text
        .trim()
        .split(/\s+/g)
        .filter((a) => a.trim().length > 0).length;
    }

    const count = `Words: ${countWords(wcParent)}`;

    // Create a shadow root
    const shadow = this.attachShadow({ mode: "open" });

    // Create text node and add word count to it
    const text = document.createElement("span");
    text.textContent = count;

    // Append it to the shadow root
    shadow.appendChild(text);

    // Update count when element content changes
    setInterval(() => {
      const count = `Words: ${countWords(wcParent)}`;
      text.textContent = count;
    }, 200);
  }
}

// Define the new element
customElements.define("word-count", WordCount, { extends: "p" });

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
attachShadow 53 79 63 No 40 10 53 53 63 41 10 6.0
init_delegatesFocus_parameter 53 79 94 No 40 13.1 53 53 94 41 13.4 6.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow