CSS Scoping Module Level 1

1. Introduction

...

2. Scoped Styles

Scoped style rules apply only within a subtree of a document, rather than matching against the entire document. Scoping has two primary effects:

• The selector of the scoped style rule is restricted to match only elements within scope. See Scoped Selectors in [SELECTORS4].

• The cascade prioritizes scoped rules over unscoped ones, regardless of specificity. See Cascading by Scope in [CSS3CASCADE].

2.1. Scoping Mechanisms

Style rules can be scoped using constructs defined in the document language or using the @scope rule in CSS.

“Scoping” consists of three somewhat independent concepts, which are in practice generally used together:

• A declaration can be scoped to a scoping root, which affects its cascading behavior. [CSS3CASCADE] (Alternately, a style rule can be scoped to a scoping root, which scopes all of the declarations it contains to that scoping root.)

• A selector can be either scope-contained or scope-filtered to a scoping root, which limits what elements it is allowed to match. [SELECTORS4]

• The :scope pseudo-class matches whatever the context sets as the :scope elements, and is used by several features, such as relative selectors. In the absence of any anything explicitly setting the :scope elements to something, the :scope pseudo-class matches the selector’s scoping root.

2.1.1. Document Markup for Scoping

Document languages may define a mechanism for a stylesheet to be scoped to some element in the document. For example, in HTML, a style element with a scoped attribute defines a stylesheet that is scoped to the style element’s parent element. [HTML]

The element that the stylesheet is scoped to is the scoping root for all the style rules in the stylesheet, and selectors of style rules in the stylesheet are scope-contained to the scoping root.

2.1.2. CSS Syntax for Scoping: the @scope rule

The @scope#at-ruledef-scopeReferenced in:2.1. Scoping Mechanisms2.1.2. CSS Syntax for Scoping: the @scope rule (2) (3) (4) (5) (6) (7) (8) at-rule allows authors to create scoped style rules using CSS syntax. The syntax of the @scope rule is:

@scope <selector> {
  <stylesheet>
}

where the elements matched by the <selector> are scoping roots for the style rules in <stylesheet>, and selectors of style rules scoped by @scope are scope-contained to their scoping root.

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 <selector>, the <stylesheet> is effectively duplicated and scoped independently to each one. Authors should avoid using overly-generic selectors as it can have confusing interactions with the cascade.

@scope div {
  span {
    color: blue;
  }
}
@scope section {
  span {
    color: orange;
  }
}

<div>
  <section>
    <div>
      <span>text</span>
    </div>
  </section>
</div>

@scope rules can be nested. In this case, just as with the nested style rules, the selector of an outer @scope scope-contains the selector of the inner one.

The specificity of selectors inside the @scope rule is calculated locally: the selector specifying the scoping element is ignored. However, because scoped styles override non-scoped styles, style rules inside the @scope will override rules outside of it.

@scope aside {
  p { color: green; }
}
aside#sidebar p { color: red; }

If multiple @scope rules apply to an element, should they be cascaded by specificity?

2.2. Querying the Scoping Context

2.2.1. Selecting the Scoping Root: :scope pseudo-class

In a scoped stylesheet, the :scope pseudo-class, defined in [SELECTORS4], matches the scoping root.

2.2.2. Selecting Outside the Scope: :scope-context() pseudo-class

:scope-context(<selector>) div {...}
scope(<selector>) div {...}
\scope <selector>\ div {...}
<selector> \scope\ div {...}

3. Shadow Encapsulation

The Shadow DOM spec augments the DOM with several new concepts, several of which are relevant to CSS.

A shadow tree#shadow-treeReferenced in:3. Shadow Encapsulation (2) (3) (4) (5) (6)3.1. Shadow DOM Selection Model (2) (3) (4)3.1.1. Host Elements in a Shadow Tree (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12)3.2.1. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) (3) (4) (5) (6) (7)3.2.2. Selecting Into the Dark: the ::shadow pseudo-element (2) (3) (4) (5) (6) (7) (8) (9)3.2.3. Selecting Shadow-Projected Content: the ::slotted pseudo-element3.2.4. Selecting Through Shadows: the >>> combinator3.3.1. Cascading (2) (3) (4) (5) (6)3.3.2. Inheritance is a document fragment that can be attached to any element in the DOM. The root of the shadow tree is a shadow root#shadow-rootReferenced in:3. Shadow Encapsulation3.2.2. Selecting Into the Dark: the ::shadow pseudo-element (2) (3), 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#youngest-shadow-treeReferenced in:3. Shadow Encapsulation for that element.

An element with a shadow tree is a shadow host#shadow-hostReferenced in:3. Shadow Encapsulation (2) (3)3.1. Shadow DOM Selection Model3.1.1. Host Elements in a Shadow Tree (2). It is the host element#host-elementReferenced in:3.1.1. Host Elements in a Shadow Tree (2) (3) (4) (5) (6)3.2.1. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) (3) (4) (5) (6)3.3.1. Cascading3.3.2. Inheritance 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#top-level-elementReferenced in:3.1. Shadow DOM Selection Model3.2.2. Selecting Into the Dark: the ::shadow pseudo-element (2)3.2.3. Selecting Shadow-Projected Content: the ::slotted pseudo-element3.3.2. Inheritance.

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#distributed-nodesReferenced in:3. Shadow Encapsulation (2)3.1. Shadow DOM Selection Model (2)3.2.1. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes3.2.3. Selecting Shadow-Projected Content: the ::slotted pseudo-element (2) (3)3.3.2. Inheritance for an insertion point#insertion-pointReferenced in:3. Shadow Encapsulation (2) (3) 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'.)

3.1. 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#in-the-context-of-a-shadow-treeReferenced in:3.2.1. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) (3) 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#rooted-in-a-shadow-treeReferenced in:3.1. Shadow DOM Selection Model.

3.1.1. 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.

3.2. Shadow DOM Selectors

Shadow DOM defines a few new selectors to help select elements in useful way related to Shadow DOM.

This section is still under discussion. Feedback and advice on intuitive syntax for the following functionality would be appreciated.

3.2.1. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes

The :host#selectordef-hostReferenced in:3.1.1. Host Elements in a Shadow Tree (2)3.2.1. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) 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()#selectordef-host-functionReferenced in:3.1.1. Host Elements in a Shadow Tree3.2.1. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes function pseudo-class has the syntax:

:host( <compound-selector> )

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>

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()#selectordef-host-contextReferenced in:2.2.2. Selecting Outside the Scope: :scope-context() pseudo-class3.1.1. Host Elements in a Shadow Tree3.2.1. Selecting Into the Light: the :host, :host(), and :host-context() pseudo-classes (2) 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> )

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 <compound-selector>. For the purpose of this pseudo-class, the "ancestor" of an element is:

if the element is a distributed node

the slot element it is ultimately distributed to.

if the element is a top-most element in a shadow tree

the host element

otherwise

the element’s parent, if it has one.

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.2. Selecting Into the Dark: the ::shadow pseudo-element

It’s been suggested to remove this feature.

If an element has at least one shadow tree, the ::shadow#selectordef-shadowReferenced in:3.2.2. Selecting Into the Dark: the ::shadow pseudo-element (2) (3) (4) (5) 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>

3.2.3. Selecting Shadow-Projected Content: the ::slotted pseudo-element

It’s been proposed to restrict this to child elements only.

The ::slotted#selectordef-slottedReferenced in:3.2.3. Selecting Shadow-Projected Content: the ::slotted pseudo-element (2) (3) (4) (5)5. Changes 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>

3.2.4. Selecting Through Shadows: the >>> combinator

It’s currently disputed whether this combinator should exist.

When a >>>#selectordef-shadow-piercing-descendant-combinatorReferenced in:3.2.4. Selecting Through Shadows: the >>> combinator 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>

3.3. Shadow Cascading & Inheritance

3.3.1. 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.

3.3.2. 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.

4. 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.

In our example, the designer wants to make text flowing into #region1 dark blue and bold. This design can be expressed as shown below.

#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 is bold instead of normal.

Note: This feature is an extension of ::first-line styling.

4.1. Region-based Styling: the ::region pseudo-element

A ::region pseudo-element represents a relationship between a selector that matches a CSS Region, and a relative selector that matches some named flow content. This allows style declarations to be applied to fragments of named flow content flowing into particular regions.

<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:

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

In the following example, the named flow “article-flow” flows into “region-1” and “region-2”.

<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>

•  div div-1
•  paragraph p-1
•  paragraph p-2
•  range of flow that fits into region-1
•  range of flow that fits into region-2

The region styling applies to flow content that fits in region-1. The relative selector matches p-1 and p-2 because these paragraphs flow into region-1. Only the fragment of p-2 that flows into region-1 is styled with the pseudo-element.

All of the selectors in a ::region pseudo-element contribute to its specificity. So the specificity of the ::region pseudo-element in the example above would combine the id selector’s specificity with the specificity of the type selector, resulting in a specificity of 101.

Selectors that match a given element or element fragment (as described above), participate in the CSS Cascading order as defined in [CSS21].

Note: Region styling does not apply to nested regions. For example, if a region A receives content from a flow that contains region B, the content that flows into B does not receive the region styling specified for region A.

We’ll need some way to query the styles of a fragment in a particular region. getComputedStyle() isn’t enough, because an element can exist in multiple regions, for example, with each fragment receiving different styles.

5. Changes

The following significant changes were made since the 3 April 2014 Working Draft.

• Renamed ::content to ::slotted.