Element.attachShadow()

Jump to:
  1. Elements you can attach a shadow to
  2. Syntax
  3. Examples
  4. Specifications
  5. Browser compatibility

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>), and more besides. The following is a list of elements you can attach a shadow root to:

Syntax

var shadowroot = element.attachShadow(shadowRootInit);

Parameters

shadowRootInit
A ShadowRootInit dictionary, which can contain 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:
      
    element.shadowRoot; // Returns a ShadowRoot obj
  • closed: Denies access to the node(s) of a closed shadow root from JavaScript outside it:
      
    element.shadowRoot; // Returns null
delegatesFocus
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. This is currently an experimental non-standard feature, available only in Chrome. See Shadow DOM v1, Handling focus for more details.

Return value

Returns a ShadowRoot object or null.

Exceptions

Exception Explanation
InvalidStateError The element you are trying to attach to is already a shadow host.
NotSupportedError You are trying to attach a shadow root to an element outside the HTML namespace, or the element cannot have a shadow attached to it (see above).

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.

// 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
    var wcParent = this.parentNode;

    function countWords(node){
      var text = node.innerText || node.textContent
      return text.trim().split(/\s+/g).length;
    }

    var count = 'Words: ' + countWords(wcParent);

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

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

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

    // Update count when element content changes
    setInterval(function() {
      var count = 'Words: ' + countWords(wcParent);
      text.textContent = count;
    }, 200)
  }
}

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

Specifications

Specification Status Comment
DOM
The definition of 'attachShadow()' in that specification.		 Living Standard  

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
attachShadowChrome Full support 53Edge No support No
Notes
No support No
Notes
Notes Under consideration
Firefox Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 40Safari Full support 10WebView Android Full support 53Chrome Android Full support 53Edge Mobile No support No
Notes
No support No
Notes
Notes Under consideration
Firefox Android Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 40Safari iOS Full support 10Samsung Internet Android ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.

Document Tags and Contributors

Tags: 
Contributors to this page: mfuji09, chrisdavidmills, dupontdenis, raingerber, ExE-Boss, jpmedley, GiS91, iamashish, DomenicDenicola, RyanNerd, valtlai, theefer, fleurdeswift, jwhitlock, tomfun, rolfedh, arthurevans
Last updated by: mfuji09,