2. Default Styles for Custom Elements
When defining custom elements,
one often wants to set up "default" styles for them,
akin to the user-agent styles that apply to built-in elements.
This is, unfortunately, hard to do in vanilla CSS,
due to issues of scoping and specificity—
To aid in this, this section defines a way to create a stylesheet of "default element styles" for a given element. This stylesheet applies across the entire document, in all shadow trees, and the rules in it apply at the user agent origin, so author-level rules automatically win.
Windows gain a private slot
[[defaultElementStylesMap]] which is a map of local names to stylesheets.
These stylesheets must apply to every document in the window. They must be interpreted as user agent stylesheets.
Note: This implies, in particular, that they apply to all shadow trees in every document, and that the declarations in them are from the user agent origin.
For the purpose of the cascade, these stylesheets are ordered after the user agent’s own stylesheets; their relative ordering doesn’t matter as it is not observable.
Within these stylesheets, complex selectors must be treated as invalid. Every compound selector must be treated as containing an additional type selector that selects elements with the local name that the stylesheet is keyed with.
Do we need to restrict the at-rules that can be used in these sheets? For example, do we allow an @font-face? I’m going to leave it as allowed unless/until I hear complaints.
This specification does not define how to add to, remove from, or generally manipulate
It is expected that other specifications,
such as [DOM],
will define ways to do so.
3. Shadow Encapsulation
3.1. Informative Explanation of Shadow DOM
The following is a non-normative explanation of several concepts normatively defined in the DOM Standard [DOM], to aid in understanding what this spec defines without having to fully grok the DOM Standard.
In addition to the qualities of an element tree defined in Selectors Level 4 §data-model, the DOM Standard adds several new concepts related to shadow trees, several of which are relevant to CSS.
An element can host a shadow tree, which is a special kind of document fragment with a shadow root (a non-element node) at its root. Children of the shadow root are ordinary elements and other nodes. The element hosting the shadow tree is its host, or shadow host.
The elements in a shadow tree are not descendants of the shadow host in general (including for the purposes of Selectors like the descendant combinator). However, the shadow tree, when it exists, is used in the construction of the flattened element tree, which CSS uses for all purposes after Selectors (including inheritance and box construction).
Loosely, the shadow tree is treated as the shadow host’s contents
instead of its normal light tree contents.
However, some of its light tree children
can be "pulled into" the shadow tree by assigning them to slots.
This causes them to be treated as children of the slot for CSS purposes.
The slots can then be assigned to slots in deeper shadow trees;
luckily, slots themselves don’t generate boxes by default,
so you don’t get an unpredictable cascade of
slot wrapper elements
disrupting your CSS.
If nothing is explicitly assigned to a slot, the slot’s own children are instead assigned to it, as a sort of "default" contents.
3.2. Shadow DOM and Selectors
3.2.1. Matching Selectors Against Shadow Trees
When a selector is matched against a shadow tree, the selector match list is initially the shadow host, followed by all children of the shadow tree’s shadow root and their descendants, ordered by a pre-order traversal.
Note: Remember that the descendants of an element are based on the light tree children of the element, which does not include the shadow trees of the element.
When a selector is matched against a tree, its tree context is the root of the root elements passed to the algorithm. If the tree context is a shadow root, that selector is being matched in the context of a shadow tree.
querySelector()when called from a shadow root.
Declarations inherit the tree context of the selector that was matched to apply them.
3.2.2. Selecting Shadow Hosts from within a Shadow Tree
A shadow host is outside of the shadow tree it hosts, and so would ordinarily be untargettable by any selectors evaluated in the context of the shadow tree (as selectors are limited to a single tree), but it is sometimes useful to be able to style it from inside the shadow tree context.
For the purpose of Selectors, a shadow host also appears in its shadow tree, with the contents of the shadow tree treated as its children. (In other words, the shadow host is treated as replacing the shadow root node.)
When considered within its own shadow trees, the shadow host is featureless. Only the :host, :host(), and :host-context() pseudo-classes are allowed to match it.
Why is the shadow host so weird?
The shadow host lives outside the shadow tree, and its markup is in control of the page author, not the component author.
It would not be very good if a component used a particular class name internally in a shadow tree stylesheet, and the page author using the component accidentally also used the the same class name and put it on the shadow host. Such a situation would result in accidental styling that is impossible for the component author to predict, and confusing for the page author to debug.
However, there are still some reasonable use-cases for letting a stylesheet in a shadow tree style its shadow host. (For example, the component might want to be laid out as a flexbox, requiring the shadow host to be set to display: flex.) So, to allow this situation but prevent accidental styling, the shadow host appears but is completely featureless and unselectable except through :host and its related functional forms, which make it very explicit when you’re trying to match against markup provided by the page author.
3.2.3. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes
The :host pseudo-class, when evaluated in the context of a shadow tree, matches the shadow tree’s shadow host. In any other context, it matches nothing.
The :host() function pseudo-class has the syntax:
:host( <compound-selector-list> )
When evaluated in the context of a shadow tree, it matches the shadow tree’s shadow host if the shadow host, in its normal context, matches the selector argument. In any other context, it matches nothing.
<x-foo class="foo"> <"shadow tree"> <div class="foo">...</div> </> </x-foo>
For a stylesheet within the shadow tree:
:host matches the
x-foo matches nothing.
.foo matches only the
.foo:host matches nothing
:host(.foo) matches the
Ordinary, selectors within a shadow tree can’t see elements outside the shadow tree at all. Sometimes, however, it’s useful to select an ancestor that lies somewhere outside the shadow tree, above it in the document.
The :host-context() functional pseudo-class tests whether there is an ancestor, outside the shadow tree, which matches a particular selector. Its syntax is:
:host-context( <compound-selector-list> )
When evaluated in the context of a shadow tree, the :host-context() pseudo-class matches the shadow host, if the shadow host or one of its shadow-including ancestors matches the provided <compound-selector-list>. In any other context, it matches nothing.
Note: This means that the selector pierces through shadow boundaries on the way up, looking for elements that match its argument, until it reaches the document root.
3.2.4. Selecting Slot-Assigned Content: the ::slotted() pseudo-element
The ::slotted() pseudo-element represents the elements assigned, after flattening, to a slot. This pseudo-element only exists on slots.
The ::slotted() pseudo-element is an alias for other elements in the tree, and does not generate any boxes itself.
The grammar of the ::slotted() pseudo-element is:
::slotted( <compound-selector-list> )
The ::slotted() pseudo-element represents the elements that are:
<x-foo> <div id="one" slot="foo" class="foo">...</div> <div id="two" slot="foo">...</div> <div id="three" class="foo"> <div id="four" slot="foo">...</div> </div> <"shadow tree"> <div id="five">...</div> <div id="six">...</div> <slot name="foo"></slot> </"shadow tree"> </x-foo>
For a stylesheet within the shadow tree,
a selector like ::slotted(*) selects #one and #two only,
as they’re the elements assigned to the sole
It will not select #three (no
nor #four (only direct children of a shadow host can be assigned to a slot).
A selector like ::slotted(.foo), on the other hand, will only select #one, as it matches .foo, but #two doesn’t.
Note: Note that a selector like ::slotted(*) is equivalent to *::slotted(*),
where the * selects many more elements than just the
However, since only the
slot elements are slots,
they’re the only elements with a ::slotted() pseudo-element as well.
Note: ::slotted() can only represent the elements assigned to the slot. Slots can also be assigned text nodes, which can’t be selected by ::slotted(). The only way to style assigned text nodes is by styling the slot and relying on inheritance.
3.2.5. Selecting Through Shadows: the >>> combinator
When a >>> combinator (or shadow-piercing descendant combinator) is encountered in a selector, replace every element in the selector match list with every element reachable from the original element by traversing any number of child lists or shadow trees.
<x-foo> <"shadow tree"> <div> <span id="not-top">...</span> </div> <span id="top">...</span> <x-bar> <"shadow tree"> <span id="nested">...</span> </> </x-bar> </> </x-foo>
For a stylesheet in the outer document,
the selector x-foo >>> span selects all three of
<span> elements: #top, #not-top, and #nested.
The shadow-piercing descendant combinator is part of the static profile of Selectors,
not the dynamic profile.
This means that it is usable in,
for example, the
but is invalid when used in stylesheets.
3.3. Shadow Trees and the Cascade
To address the desired cascading behavior of rules targetting elements in shadow roots, this specification extends the cascade order defined in the Cascade specification. [CSS3CASCADE]
An additional cascade criteria must be added, between Origin and Scope, called Shadow Tree.
When comparing two declarations that have different tree contexts, then for normal rules the declaration earlier in the shadow-including tree order wins, and for important rules the declaration coming later in the shadow-including tree order wins.
Note: This is the opposite of how scoped styles work.
3.4. Flattening the DOM into an Element Tree
While Selectors operates on the DOM tree as the host language presents it, with separate trees that are unreachable via the standard parent/child relationship, the rest of CSS needs a single unified tree structure to work with. This is called the flattened element tree (or flat tree), and is constructed as follows:
Let pending nodes be a list of DOM nodes with associated parents, initially containing just the document’s root element with no associated parent.
Repeatedly execute the following substeps until pending nodes is empty:
Pop the first element from pending nodes, and assign it to pending node.
Insert pending node into the flat tree as a child of its associated parent. (If it has no associated parent, it’s the document root—
just insert it into the flat tree as its root.)
Perform one of the following, whichever is the first that matches:
- pending node is a shadow host
- Append the child nodes of the shadow root of the shadow tree it hosts to pending nodes, with pending node as their associated parent.
- pending node is a slot
Find slotables for pending node,
and append them to pending nodes,
with pending node as their associated parent.
If no slotables were found for pending node, instead append its children to pending nodes, with pending node as their associated parent.
- Append the child nodes of pending node’s light tree to pending nodes, with pending node as their associated parent.
Note: In other words, the flat tree is the top-level DOM tree, but shadow hosts are filled with their shadow tree children instead of their light tree children (and this proceeds recursively if the shadow tree contains any shadow hosts), and slots get filled with the nodes that are assigned to them (and this proceeds recursively if the slots are themselves assigned to a slot in a deeper shadow tree).
A non-obvious result of this is that elements assigned to a slot inherit from that slot, not their light-tree parent or any deeper slots their slot gets assigned to. This means that text nodes are styled by the shadow tree of their parent, with nobody else capable of intervening in any way. Do we want an additional pseudo-element for targeting those text nodes so they can be styled at all slot-assignment levels, like normal elements can be? This implies it needs to work for text nodes in the light tree before they’re assigned downwards, so this can’t just be a ::slotted() variant. Luckily, this is a long-standing request!
3.4.1. Slots and Slotted Elements in a Shadow Tree
Slots must act as if they were assigned display: contents via a rule in the UA origin. This must be possible to override via display, so they do generate boxes if desired.
Note: A non-obvious result of assigning elements to slots is that they inherit from the slot they’re assigned to. Their original light tree parent, and any deeper slots that their slot gets assigned to, don’t affect inheritance.
The following significant changes were made since the 3 April 2014 Working Draft.
Renamed ::content to ::slotted.
Define the flattened tree
Generally reorg and rebase the Shadow DOM section on top of current DOM.
Punt @scope and related things, and ::region and related things, to the next level of the draft.
5. Privacy and Security Considerations
This specification introduces Shadow DOM and some shadow-piercing capabilities,
but this does not introduce any privacy or security issues—