This rule makes it very easy for authors to create scoped style sheets,
which could affect the optimization strategies for implementing scoped styles.
If multiple elements match the <
@scope div {
span {
color: blue;
}
}
@scope section {
span {
color: orange;
}
}
and the following document fragment
<div>
<section>
<div>
<span>text</span>
</div>
</section>
</div>
the text will be blue.
@scope aside {
p { color: green; }
}
aside#sidebar p { color: red; }
Querying the Scoping Context
Selecting the Scoping Root: '':scope'' pseudo-class
In a scoped stylesheet,
the '':scope'' pseudo-class,
defined in [[SELECTORS4]],
matches the scoping root.
Selecting Outside the Scope: '':scope-context()'' pseudo-class
:scope-context(<
This functionality would replace ''@global'', which is a poor excuse for a selector.
Shadow Encapsulation
The Shadow DOM spec augments the DOM with several new concepts,
several of which are relevant to CSS.
A shadow tree is a document fragment
that can be attached to any element in the DOM.
The root of the shadow tree is a shadow root,
a non-element node which is associated with a shadow host.
An element can have any number of shadow trees,
which are ordered by creation time.
The most recently-created shadow tree on an element
is the youngest shadow tree for that element.
An element with a shadow tree is a shadow host.
It is the host element for its shadow trees.
The descendants of a shadow host
must not generate boxes in the formatting tree.
Instead, the contents of the youngest shadow tree generate boxes
as if they were the contents of the element instead.
In several instances in shadow DOM,
elements don't have element parents
(instead, they may have a shadow root as parent,
or something else).
An element without a parent,
or whose parent is not an element,
is called a top-level element.
While the children of a shadow host do not generate boxes normally,
they can be explicitly pulled into a shadow tree and forced to render normally.
This is done by marking the elements as distributed nodes
for an insertion point element.
This specification does not define how to mark elements as distributed nodes,
instead leaving that to the Shadow DOM spec.
At the time this spec is written, however,
only slot elements in a shadow tree can be insertion points.
An insertion point must not generate any boxes.
Instead, its distributed nodes generate boxes as normal,
as if they all replaced the insertion point in-place.
(Akin to the behavior of 'display-outside: contents'.)
Shadow DOM Selection Model
Elements in the DOM
have zero or more shadow trees
and zero or more distributed nodes.
Note: The "descendants" of an element
are based on the children of the element,
which does not include the shadow trees or distributed nodes of the element.
When a selector is matched against a shadow tree,
the selector match list
is initially the shadow host,
followed by all the top-level elements of the shadow tree
and their descendants,
ordered by a pre-order traversal.
A selector is in the context of a shadow tree
if it is in a stylesheet attached to the shadow tree
(that is, present in the ShadowRoot.styleSheets list),
or it is used in an API that is rooted in a shadow tree.
querySelector()/etc are rooted in a shadow tree
if they're called on a ShadowRoot or an element in a shadow tree.
Host Elements in a Shadow Tree
A shadow host is outside of the shadow trees it hosts,
but it is sometimes useful to be able to style it from inside the shadow tree context.
For the purpose of Selectors,
a host element also appears in each of its shadow trees,
with the contents of the shadow tree treated as its children.
If an element has multiple shadow trees,
it appears in each shadow tree's context independently;
each shadow tree sees itself as the contents of the host element,
not the other shadow trees.
When considered within its own shadow trees,
the host element 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,
and the page author using the component accidentally also
used the the same class name and put it on the host element.
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 host element.
So, to allow this situation but prevent accidental styling,
the host element appears but is completely featureless
and unselectable except through '':host''.
Shadow DOM Selectors
Shadow DOM defines a few new selectors
to help select elements in useful way related to Shadow DOM.
Issue: This section is still under discussion.
Feedback and advice on intuitive syntax for the following functionality
would be appreciated.
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 host element.
In any other context,
it matches nothing.
The :host() function pseudo-class
has the syntax:
:host( <
When evaluated in the context of a shadow tree,
it matches the shadow tree's host element
if the host element,
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> element.
* ''x-foo'' matches nothing.
* ''.foo'' matches only the <div> element.
* ''.foo:host'' matches nothing
* '':host(.foo)'' matches the <x-foo> element.
:host-context( <
When evaluated in the context of a shadow tree,
the '':host-context()'' pseudo-class matches the host element,
if the host element or one of its ancestors matches the provided <
Selecting Into the Dark: the ''::shadow'' pseudo-element
Issue: It's been suggested to remove this feature.
If an element has at least one shadow tree,
the ::shadow pseudo-element matches the shadow roots themselves.
In HTML, the shadow root is represented by {{ShadowRoot}} objects.
The ''::shadow'' pseudo-element must not generate boxes,
unless specified otherwise in another specification.
However, for the purpose of Selectors,
the ''::shadow'' pseudo-element is considered to be the root of the shadow tree,
with the top-level elements in the shadow tree the direct children of the ''::shadow'' pseudo-element.
<x-foo>
<"shadow tree">
<div>
<span id="not-top">...</span>
</div>
<span id="top">...</span>
</>
</x-foo>
For a stylesheet in the outer document,
''x-foo::shadow > span'' matches ''#top'',
but not ''#not-top'',
because it's not a top-level element in the shadow tree.
If one wanted to target ''#not-top'',
one way to do it would be with ''x-foo::shadow > div > span''.
However, this introduces a strong dependency on the internal structure of the component;
in most cases, it's better to use the descendant combinator,
like ''x-foo::shadow span'',
to select all the elements of some type in the shadow tree.
Selecting Shadow-Projected Content: the ''::slotted'' pseudo-element
Issue: It's been proposed to restrict this to child elements only.
The ::slotted pseudo-element
matches the list of distributed nodes itself,
on elements that have them.
The ''::slotted'' pseudo-element must not generate boxes,
unless specified otherwise in another specification.
However, for the purpose of Selectors,
the ''::slotted'' pseudo-element is considered to be a parent of the distributed nodes.
<x-foo>
<div id="one" class="foo">...</div>
<div id="two">...</div>
<div id="three" class="foo">
<div id="four">...</div>
</div>
<"shadow tree">
<div id="five">...</div>
<div id="six">...</div>
<content select=".foo"></content>
</"shadow tree">
</x-foo>
For a stylesheet within the shadow tree,
a selector like ''::slotted div''
selects ''#one'', ''#three'', and ''#four'',
as they're the elements distributed by the sole slot element,
but not ''#two''.
If only the top-level elements distributed the slot element are desired,
a child combinator can be used,
like ''::slotted > div'',
which will exclude ''#four''
as it's not treated as a child of the ''::slotted'' pseudo-element.
Note: Note that a selector like ''::slotted div''
is equivalent to ''*::slotted div'',
where the ''*'' selects many more elements that just the slot element.
However, since only the slot element has distributed nodes,
it's the only element that has a ''::slotted'' pseudo-element as well.
Selecting Through Shadows: the ''>>>'' combinator
Issue: It's currently disputed whether this combinator should exist.
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''.
Shadow Cascading & Inheritance
Cascading
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,
if one of them is in a shadow tree
and the other is in a document that contains that shadow tree,
then for normal rules the declaration from the outer document wins,
and for important rules the declaration from the shadow tree wins.
Note: This is the opposite of how scoped styles work.
* When comparing two declarations,
if both are in shadow trees with the same host element,
then for normal rules the declaration from the shadow tree that was created most recently wins,
and for important rules the declaration from the shadow tree that was created less recently wins.
When calculating Order of Appearance,
the tree of trees,
defined by the Shadow DOM specification,
is used to calculate ordering.
Inheritance
The top-level elements of a shadow tree
inherit from their host element.
Distributed nodes inherit from the parent of the slot element they are ultimately distributed to,
rather than from their normal parent.
Fragmented Styling
Fragmented content can be styled differently
based on which line, column, page, region, etc.
it appears in.
This is done by using an appropriate fragment pseudo-element,
which allows targetting individual fragments of an element
rather than the entire element.
#region1::region p {
color: #0C3D5F;
font-weight: bold;
}
The ''::region'' pseudo-element
is followed by a ''p'' relative selector in this example.
The color and font-weight declarations will apply
to any fragments of paragraphs that are
displayed in ''#region1''.
The following figure shows how
the rendering changes
if we apply this styling specific to ''#region1''.
Note how less text fits into this box
now that the 'font-weight!!property' is
bold instead of normal.
Region-based Styling: the ''::region'' pseudo-element
<region selector>::region <content selector> {
... CSS styling declarations ...
}
When the ::region pseudo-element is appended to a
selector
that matches one or more CSS Regions,
this creates a 'flow fragment' selector.
The flow fragment selector specifies
which range of elements in the flow
can be matched by the relative selector.
The relative selector can match elements
in the range(s) (see [[!DOM]]) of the named flow
that are displayed fully or partially
in the selected region(s).
Elements that are fully or partially
in the flow fragment range may match the relative selector.
However, the style declarations only apply
to the fragment of the element
that is displayed in the corresponding region(s).
Only a limited list of properties apply to a ::region pseudo-element:
Issue: Either this list should be all functionally inheritable properties,
or all properties.
Why is it a seemingly-arbitrary subset of all properties, including box properties?
1. font properties
2. color property
3. opacity property
4. background property
5. 'word-spacing'
6. 'letter-spacing'
7. 'text-decoration'
8. 'text-transform'
9. 'line-height'
10. alignment and justification properties
11. border properties
12. rounded corner properties
13. border images properties
14. margin properties
15. padding properties
16. 'text-shadow'
17. 'box-shadow'
18. 'box-decoration-break'
19. 'width'
<style>
#div-1 {
flow-into: article-flow;
}
#region-1, #region-2 {
flow-from: article-flow;
}
/* region styling */
#region-1::region p {
margin-right: 5em;
}
</style>
<body>
<div id="div-1">
<p id="p-1">...</p>
<p id="p-2">...</p>
</div>
<div id="region-1"></div>
<div id="region-2"></div>
</body>
getComputedStyle() isn't enough,
because an element can exist in multiple regions, for example,
with each fragment receiving different styles.
Changes
The following significant changes were made since the
3 April 2014 Working Draft.
* Renamed