This specification contains leftover shadow DOM-related definitions which are not yet given a more permanent home in other specifications.

Not an active specification Most of the Shadow DOM specification has been upstreamed to DOM [[DOM]], HTML [[HTML]], CSS Scoping [[css-scoping-1]], UI Events [[uievents]], and other relevant specifications. What remains here is stuff which has not yet been properly vetted and integrated into the specification ecosystem. As such, the contents here are not fully reliable. See Issue #377 for details.

User Interaction

Ranges and Selections

Selection [[!EDITING]] is not defined. Implementation should do their best to do what's best for them. Here's one possible, admittedly naive way:

Since nodes which are in the different node trees never have the same root, there may never exist a valid DOM range that spans multiple node trees.

Accordingly, selections may only exist within one node tree, because they are defined by a single range. The selection, returned by the window.getSelection() method never returns a selection within a shadow tree.

The getSelection() method of the shadow root object returns the current selection in this shadow tree.


The value of the contenteditable attribute must not propagate from shadow host to its shadow trees.

Assistive Technology

User agents with assistive technology traverse the flat tree, and thus enable full use of WAI-ARIA [[!WAI-ARIA]] semantics in the shadow trees.

Hit Testing

When a text node is a child node of a shadow root, a hit testing must target the shadow host if the text node is the result of the hit testing.

User-agent mouse events must be targeted to the parent node in the flat tree of a text node if the topmost event target is the text node.

This section eventually needs to be part of some general hit testing specification.

HTML Elements in Shadow Trees

Inertness of HTML Elements in a shadow tree

Comparatively, a shadow tree can be seen as somewhere between just part of a document and itself being a document fragment. Since it is rendered, a shadow tree aims to retain the traits of a typical tree in a document. At the same time, it is an encapsulation abstraction, so it has to avoid affecting the document tree. Thus, the HTML elements must behave as specified [[!HTML]] in the shadow trees, with a few exceptions.

According to the [[!HTML]], some HTML Elements would have different behavior if they participate in a shadow tree, instead of a document tree, because their definitions require the elements to be in a document as a necessary condition for them to work. In other words, they shouldn't work if they participate in a shadow tree, even when they are in a shadow-including document. We must fill this gap because we expect that most of HTML Elements behave in the same way as in a document, as long as they are in a shadow-including document. See W3C Bug 26365 and Bug 27406 for the details. The following is the tentative summary of the discussions in the W3C bugs. We, however, haven't covered all HTML Elements and their behaviors here yet. For HTML Elements which are not explicitly stated here, they should *work* even in a shadow tree. We are trying to update [[!HTML]] itself, instead of having monkey patches here. If [[!HTML]] explains an element's behavior explicitly, it should be honored, instead of this section.

Some HTML Elements are classified into the following categories:


When [[!HTML]] defines the processing algorithms to traverse trees for the following attributes, they must use the flat tree.

role and ARIA are defined in Assistive Technology.

Other Clarifications

This section is used to state what needs to be clarified. Each clarification will be upstreamed to the HTML Standard or other specifications, eventually, if required.

Style elements inside a shadow tree must not be able to set the preferred style sheet set for the document tree. Style elements inside a shadow tree should still be applied if it has a title attribute not matching the preferred style sheet set of the document tree. See Issue #391.

An iframe in a shadow tree must not have any effect on window.history neither window.frames. See Issue #184.

:root pseudo class does not match any element if the rule is used in a shadow tree.

Elements and DOM interfaces

Extensions to the DocumentOrShadowRoot Mixin

          partial interface DocumentOrShadowRoot {
            Selection? getSelection ();
            Element? elementFromPoint(double x, double y);
            sequence<Element> elementsFromPoint(double x, double y);
            CaretPosition? caretPositionFromPoint(double x, double y);


David Hyatt developed XBL 1.0, and Ian Hickson co-wrote XBL 2.0. These documents provided tremendous insight into the problem of functional encapsulation and greatly influenced this specification.

Alex Russell and his considerable forethought triggered a new wave of enthusiasm around the subject of shadow DOM and how it can be applied practically on the Web.

Dominic Cooney, Hajime Morrita, and Roland Steiner worked tirelessly to scope the problem of functional encapsulation within the confines of the Web platform and provided a solid foundation for this document.

The editor would also like to thank Alex Komoroske, Anne van Kesteren, Brandon Payton, Brian Kardell, Darin Fisher, Eric Bidelman, Deepak Sherveghar, Edward O'Connor, Elisée Maurer, Elliott Sprehn, Erik Arvidsson, Glenn Adams, Jonas Sicking, Koji Ishii, Malte Ubl, Mike Taylor, Oliver Nightingale, Olli Pettay, Rafael Weinstein, Richard Bradshaw, Ruud Steltenpool, Sam Dutton, Sergey G. Grekhov, Shinya Kawanaka, Tab Atkins, Takashi Sakamoto, and Yoshinori Sano for their comments and contributions to this specification.