Using the Shadow Root in Server-side Elements

The Element API supports adding a shadow root to element types that support this. This allows you to create server-side Web Components.

You can use the element.attachShadow() method to add a shadow root.

Example: Using the element.attachShadow method to add a shadow root node.

Java

Element element = new Element("custom-element");
ShadowRoot shadowRoot = element.attachShadow();

Note:

• A ShadowRoot is not an actual element. Its purpose is to support handling of child elements and getting the host element that contains the shadow root.

• Elements added to a ShadowRoot parent are only visible if the ShadowRoot contains a <slot></slot> element. See Server-side components in Polymer 2 templates for more.

To ensure that new elements are encapsulated in the shadow tree of the hosting element, you should add all new elements to the ShadowRoot element.

Example: Adding an element to the ShadowRoot.

Java

@Tag("my-label")
public class MyLabel extends Component {
    public MyLabel() {
        ShadowRoot shadowRoot = getElement()
                .attachShadow();
        Label textLabel = new Label("In the shadow");
        shadowRoot.appendChild(textLabel.getElement());
    }
}

Elements That Do Not Support a Shadow Root

The DOM specification defines a list of elements that can’t host a shadow tree. Typical reasons for this include:

• The browser already hosts its own internal shadow DOM for the element, for example. <textarea> and <input>.

• It doesn’t make sense for the element to host a shadow DOM, for example <img>.