IssueTracker

Problem

In the Component Hydration content, the following explanation about checking for any existing shadow root in your element's constructor is incorrect.

A Custom Element being upgraded from HTML that includes a Declarative Shadow Root will already have that shadow root attached. This means the element will have a shadowRoot property already available when it is instantiated, without your code explicitly creating one. It's best to check this.shadowRoot for any existing shadow root in your element's constructor. If there is already a value, the HTML for this component includes a Declarative Shadow Root. If the value is null, there was no Declarative Shadow Root present in the HTML or the browser doesn't support Declarative Shadow DOM.

This is only true for shadow root's with shadowrootmode="open". There are actually 3 reasons the value can be null, not two as the existing contents states:

If the value is null:

1. there was no Declarative Shadow Root present in the HTML
2. the browser doesn't support Declarative Shadow DOM
3. the broswer supports Declarative Shadow DOM but the Shadow Root was attached with shadowrootmode="closed"

Similarly the example that follows is also an incorrect strategy for dealing with Shadow Roots added during SSR (or at least only useful for shadow root's with shadowrootmode="open").

<menu-toggle>
  <template shadowrootmode="open">
    <button>
      <slot></slot>
    </button>
  </template>
  Open Menu
</menu-toggle>
<script>
  class MenuToggle extends HTMLElement {
    constructor() {
      super();

      // Detect whether we have SSR content already:
      if (this.shadowRoot) {
        // A Declarative Shadow Root exists!
        // wire up event listeners, references, etc.:
        const button = this.shadowRoot.firstElementChild;
        button.addEventListener('click', toggle);
      } else {
        // A Declarative Shadow Root doesn't exist.
        // Create a new shadow root and populate it:
        const shadow = this.attachShadow({mode: 'open'});
        shadow.innerHTML = `<button><slot></slot></button>`;
        shadow.firstChild.addEventListener('click', toggle);
      }
    }
  }

  customElements.define('menu-toggle', MenuToggle);
</script>

Again, this is only useful for the limited case where shadowrootmode="open". Change shadowrootmode to "closed" and debug the constructor to see the current code will re-attach the shadow unnecessarily. A more general solution which covers all cases should be shown instead. There is already a code example (follows below) for a general solution that uses ElementInternals.shadowRoot instead of this.shadowRoot, so introducing the above example is confusing at best.

class MenuToggle extends HTMLElement {
  constructor() {
    super();

    const internals = this.attachInternals();

    // check for a Declarative Shadow Root:
    let shadow = internals.shadowRoot;

    if (!shadow) {
      // there wasn't one. create a new Shadow Root:
      shadow = this.attachShadow({
        mode: 'open'
      });
      shadow.innerHTML = `<button><slot></slot></button>`;
    }

    // in either case, wire up our event listener:
    shadow.firstChild.addEventListener('click', toggle);
  }
}

customElements.define('menu-toggle', MenuToggle);

Potential Fix

To solve these issue, you will need to introduce ElementInternals.shadowRoot before you introduce the SSR problem and example (i.e. handling previously rendered declarative Shadow DOM). This is so that the example can use ElementInternals.shadowRoot instead of this.shadowRoot which will be null if the closed mode is used. Here is a potential flow which mostly just re-orders the content and removes the unnecessary first code example (merging some parts with the second example).

Custom Elements and detecting existing Shadow Roots

Edit Note: new section with content moved from "Component hydration" section

Declarative Shadow DOM can be used on its own as a way to encapsulate styles or customize child placement, but it's most powerful when used with Custom Elements. Components built using Custom Elements get automatically upgraded from static HTML. With the introduction of Declarative Shadow DOM, it's now possible for a Custom Element to have a shadow root before it gets upgraded.

Custom Elements have been around for a while, and until now there was no reason to check for an existing shadow root before creating one using attachShadow(). Declarative Shadow DOM includes a small change that allows existing components to work despite this: calling the attachShadow() method on an element with an existing Declarative Shadow Root will not throw an error. Instead, the Declarative Shadow Root is emptied and returned. This allows older components not built for Declarative Shadow DOM to continue working, since declarative roots are preserved until an imperative replacement is created.

For newly-created Custom Elements, a new ElementInternals.shadowRoot property provides an explicit way to get a reference to an element's existing Declarative Shadow Root, both open and closed. This can be used to check for and use any Declarative Shadow Root, while still falling back to attachShadow() in cases where one was not provided.

Component hydration

Edit Note: existing section with content removed, changed and clarified since the shadowRoot property cannot be relied on due to closed roots

A Custom Element being upgraded from HTML that includes a Declarative Shadow Root will already have that shadow root attached. This means the element's ElementInternals will have a shadowRoot property already available when it is instantiated, without your code explicitly creating one. It's best to check ElementInternals.shadowRoot for any existing shadow root in your element's constructor. If there is already a value, the HTML for this component includes a Declarative Shadow Root. If the value is null, there was no Declarative Shadow Root present in the HTML or the browser doesn't support Declarative Shadow DOM.

Edit Note: merged example that takes the <menu-toggle> html from first example and adds it to the second (correct) example that allows for closed roots - also added an implementation of toggle and changed firstChild to firstElementChild so the code sample actually works - firstChild can otherwise be a Text Node

<menu-toggle>
    <template shadowrootmode="open">
        <button>
            <slot></slot>
        </button>
    </template>
    Open Menu
</menu-toggle>

<script>
    const toggle = () => {
        alert('menu toggled!');
    }

    class MenuToggle extends HTMLElement {
        constructor() {
            super();

            const internals = this.attachInternals();

            // check for a Declarative Shadow Root:
            let shadow = internals.shadowRoot;

            if (!shadow) {
                // there wasn't one. create a new Shadow Root:
                shadow = this.attachShadow({
                    mode: 'open'
                });
                shadow.innerHTML = `<button><slot></slot></button>`;
            }

            // in either case, wire up our event listener:
            shadow.firstElementChild.addEventListener('click', toggle);
        }
    }

    customElements.define('menu-toggle', MenuToggle);
</script>