CSS Cascading and Inheritance Level 6

Editor’s Draft,

Specification Metadata
This version:
https://drafts.csswg.org/css-cascade-6/
Latest published version:
https://www.w3.org/TR/css-cascade-6/
Issue Tracking:
CSSWG Issues Repository
Inline In Spec
Editors:
Elika J. Etemad / fantasai (Invited Expert)
Miriam E. Suzanne (Invited Expert)
Tab Atkins Jr. (Google)
Suggest an Edit for this Spec:
GitHub Editor

Abstract

This CSS module describes how to collate style rules and assign values to all properties on all elements. By way of cascading and inheritance, values are propagated for all properties on all elements.

New in this level is § 2.5 Scoped Styles.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “css-cascade” in the title, like this: “[css-cascade] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 15 September 2020 W3C Process Document.

1. Introduction and Missing Sections

@import

In all current engines.

Firefox1+Safari1+Chrome1+
Opera3.5+Edge79+
Edge (Legacy)12+IE5.5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile10.1+

all

In all current engines.

Firefox27+Safari9.1+Chrome37+
Opera24+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android27+iOS Safari9.3+Chrome for Android37+Android WebView37+Samsung Internet3.0+Opera Mobile24+

inherit

In all current engines.

Firefox1+Safari1+Chrome1+
Opera4+Edge79+
Edge (Legacy)12+IE8+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile14+

initial

In all current engines.

Firefox19+Safari1.2+Chrome1+
Opera15+Edge79+
Edge (Legacy)13+IENone
Firefox for Android19+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile14+

revert

In all current engines.

Firefox67+Safari9.1+Chrome84+
Opera70+Edge84+
Edge (Legacy)NoneIENone
Firefox for Android67+iOS Safari9.3+Chrome for Android84+Android WebView84+Samsung Internet14.0+Opera Mobile60+

unset

In all current engines.

Firefox27+Safari9.1+Chrome41+
Opera28+Edge79+
Edge (Legacy)13+IENone
Firefox for Android27+iOS Safari9.3+Chrome for Android41+Android WebView41+Samsung Internet4.0+Opera Mobile28+

This is a diff spec over CSS Cascading and Inheritance Level 5. It is currently an Exploratory Working Draft: if you are implementing anything, please use Level 5 as a reference. We will merge the Level 5 text into this draft once it reaches CR.

2. Cascading

The cascade takes an unordered list of declared values for a given property on a given element, sorts them by their declaration’s precedence as determined below, and outputs a single cascaded value.

2.1. Cascade Sorting Order

The cascade sorts declarations according to the following criteria, in descending order of priority:

Origin and Importance
The origin of a declaration is based on where it comes from and its importance is whether or not it is declared with !important (see below). The precedence of the various origins is, in descending order:
  1. Transition declarations [css-transitions-1]
  2. Important user agent declarations
  3. Important user declarations
  4. Important author declarations
  5. Animation declarations [css-animations-1]
  6. Normal author declarations
  7. Normal user declarations
  8. Normal user agent declarations

Declarations from origins earlier in this list win over declarations from later origins.

Context
A document language can provide for blending declarations sourced from different encapsulation contexts, such as the nested tree contexts of shadow trees in the [DOM].

When comparing two declarations that are sourced from different encapsulation contexts, then for normal rules the declaration from the outer context wins, and for important rules the declaration from the inner context wins. For this purpose, [DOM] tree contexts are considered to be nested in shadow-including tree order.

Note: This effectively means that normal declarations belonging to an encapsulation context can set defaults that are easily overridden by the outer context, while important declarations belonging to an encapsulation context can enforce requirements that cannot be overridden by the outer context.

The Style Attribute
Separately for normal and important declarations, declarations that are attached directly to an element (such as the contents of a style attribute) rather than indirectly mapped by means of a style rule selector take precedence over declarations the same importance that are mapped via style rule.
Layers
Declarations within each origin and context can be explicitly assigned to a cascade layer. For the purpose of this step, any declaration not assigned to an explicit layer is added to an implicit final layer.

Cascade layers (like declarations) are ordered by order of appearance. When comparing declarations that belong to different layers, then for normal rules the declaration whose cascade layer is last wins, and for important rules the declaration whose cascade layer is first wins.

Note: This follows the same logic used for layering normal and important origins, so that the !important flag maintains the same “override” purpose in both settings.

Strong Scoping Proximity
If two declarations both have elements selected by scoped descendant relationships applying strong scoping proximity, then the declaration with the fewest generational hops between the ancestor/descendant element pair wins.

If multiple such pairs are represented, their strong scoping proximity weights are compared from innermost scoping relationship to outermost scoping relationship (with any missing pairs weighted as infinity).

Specificity
The Selectors module [SELECT] describes how to compute the specificity of a selector. Each declaration has the same specificity as the style rule it appears in. The declaration with the highest specificity wins.
Weak Scoping Proximity
If two declarations both have elements selected by scoped descendant relationships applying weak scoping proximity, then the declaration with the fewest generational hops between the ancestor/descendant element pair wins.

If multiple such pairs are represented, their weak scoping proximity weights are compared from innermost scoping relationship to outermost scoping relationship (with any missing pairs weighted as infinity).

Order of Appearance
The last declaration in document order wins. For this purpose:
  • Style sheets are ordered as in final CSS style sheets.
  • Declarations from imported style sheets are ordered as if their style sheets were substituted in place of the @import rule.
  • Declarations from style sheets independently linked by the originating document are treated as if they were concatenated in linking order, as determined by the host document language.
  • Declarations from style attributes are ordered according to the document order of the element the style attribute appears on, and are all placed after any style sheets.

Does scope proximity belong above or below specificity in the cascade?

The output of the cascade is a (potentially empty) sorted list of declared values for each property on each element.

2.2. Cascading Origins

CSS Cascading 5 § 6.2 Cascading Origins

cascade origin

2.3. Important Declarations: the !important annotation

CSS Cascading 5 § 6.3 Important Declarations: the !important annotation

important normal

2.4. Cascade Layers

CSS Cascading 5 § 6.4 Cascade Layers

2.5. Scoped Styles

A scope is a subtree or fragment of a document, which can be used by selectors for more targeted matching. Scopes are described in CSS through a combination of two selector lists:

Each resulting scope includes a scoping root and all its descendants, up to and including any scoping limit elements, but not the descendants of those limits.

Inclusive vs exclusive scope boundaries [Issue #6577]

Note: In contrast to Shadow Encapsulation, which describes a persistent one-to-one relationship in the DOM between a shadow host and its nested shadow tree, multiple overlapping scopes can be defined in relation to the same elements.

For example, an author might have wide-reaching color-scheme scopes, which overlap more narrowly-scoped design patterns such as a media object:
@scope (.light-scheme) {
  a { color: darkmagenta; }
}

@scope (.dark-scheme) {
  a { color: plum; }
}

@scope (.media-object) {
  .media-image { border-radius: 50%; }
  .media-content { padding: 1em; }
}
By providing scoping limits, an author can limit matching more deeply nested descendants. For example:
@scope (.media-object) to (.content) {
  img { border-radius: 50%; }

  /* it is also possible to style the lower limit element itself */
  .content { padding: 1em; }
}

The img selector will only match image tags that are in a DOM fragment starting with any .media-object, and including all descendants until any intervening .content class.

Should scoping limits be added to the definition of scoped selectors?

Scoping limits can use the :scope pseudo-class to require a specific relationship to the scoping root:
/* .content is only a limit when it is a direct child of the :scope */
@scope (.media-object) to (:scope > .content) { ... }

Scoping limits can also reference elements outside their scoping root by using :scope. For example:

/* .content is only a limit when the :scope is inside .sidebar */
@scope (.media-object) to (.sidebar :scope .content) { ... }

2.5.1. Strong Scoping: the @scope rule

The @scope block at-rule allows authors to scope style rules in CSS, with the application of scoping proximity between the scoping root and the subject of each style rule.

Should @scope use strong or weak scoping proximity? Strong scoping proximity causes declarations to be weighted more strongly by scope proximity than by their selector’s specificity. Weak scoping proximity causes declarations of the same specificity to be weighted by proximity to their scoping root before falling back to source ordering, but declarations of higher specificity win over more tightly-scoped declarations.

The syntax of the @scope rule is:

@scope (<scope-start>) [to (<scope-end>)]? {
  <stylesheet>
}

The @scope at-rule has three primary effects on the style rules in its <stylesheet>:

The following selectors have the same specificity (1,0,1):
@scope (#hero) {
  img { border-radius: 50%; }
}

#hero img { border-radius: 50%; }

But because img is scoped, it is weighted more strongly in the cascade.

Many existing tools implement "scoped styles" by applying a unique class or attribute to every element in a given scope or "single file component." In this example there are two scopes (main-component and sub-component) and every element is marked as part of one or both scopes using the data-scope attribute:
<section data-scope="main-component">
  <p data-scope="main-component">...<p>

  <!-- sub-component root is in both scopes -->
  <section data-scope="main-component sub-component">
    <!-- children are only in the inner scope -->
    <p data-scope="sub-component">...<p>
  </section>
</section>

Those custom scope attributes are then appended to every single selector in CSS:

p[data-scope~='main-component'] { color: red; }
p[data-scope~='sub-component'] { color: blue; }

/* both sections are part of the outer scope */
section[data-scope~='main-component'] { background: snow; }

/* the inner section is also part of the inner scope */
section[data-scope~='sub-component'] { color: ghostwhite; }

Using the @scope rule, authors and tools can replicate similar behavior with the unique attribute or class applied only to the scoping roots:

<section data-scope="main-component">
  <p>...<p>
  <section data-scope="sub-component">
    <!-- children are only in the inner scope -->
    <p>...<p>
  </section>
</section>

Then the class or attribute can be used for establishing both upper and lower boundaries, such that scopes only overlap at those boundaries:

@scope ([data-scope='main-component']) to ([data-scope]) {
  p { color: red; }

  /* both sections are part of the outer scope */
  section { background: snow; }
}

@scope ([data-scope='sub-component']) to ([data-scope]) {
  p { color: blue; }

  /* the inner section is also part of the inner scope */
  section { color: ghostwhite; }
}

@scope rules can be nested. In this case, just as with the nested style rules, the selectors of the inner @scope (including those defining its scope) are scoped by the selectors of the outer one.

2.5.2. Scoped Descendant Combinator

The scoped descendant combinator describes a descendant relationship between two elements. A selector of the form A >> B represents an element B that is an arbitrary descendant of some ancestor element A.

This combinator differs from the descendant combinator in that it applies weak scoping proximity to the relationship between A and B. It does not change the :scope element.

Should the scoped descendant combinator use strong or weak scoping proximity? Should it even exist? It’s defined here to work the way many people expected the regular descendant combinator to work...

This means that style rules using the scoped descendant combinator are sorted by specificity just like the regular descendant combinator, except that when their specificities are equal the more tightly-scoped declaration wins.

In this example the <a> element’s color will be determined by the nearest ancestor with either a light-scheme or dark-scheme class. (If the descendant selector had been used, its color would always be plum, because it is later in the source order.)

.light-scheme >> a { color: darkmagenta; }
.dark-scheme >> a { color: plum; }

However if the <a> element has a light-scheme ancestor and is focused, its color will be teal even if it has a nearer dark-scheme ancestor, because there is no equivalent dark-scheme rule.

.light-scheme >> a:focus { color: teal; }

Note: Most simple scoping relationships can be represented with this syntax, rather than the more complex selector scoping notation defined below.

2.5.3. Selector Scoping Notation

The selector scoping notation allows selectors to be scoped to a subtree of the document, and allows the possibility of excluding nested subtrees. It is prepended to the selector or selector list, and its syntax is as follows:

<selector-scope> = ( <scope-start> [/ <scope-end>]? )

If, after parsing, <scope-start> is an empty list, the selector is valid but matches nothing. Otherwise, the selector matches any element that is within the scope described by the given <scope-start> and <scope-end> selectors.

The purpose of the selector scoping notation is to allow adding scoping limits to a selector:
(.post / .comments) .title { font-size: 2em; }

Without any such lower limits, the selector scoping notation is similar to existing descendant selectors, except that the scoping root can be matched by the selector as well.

The specificity of the most specific complex selector in <scope-start> is added to the specificity of each such scoped selector. The specificity of the <scope-end> is ignored. The selector scoping notation also applies weak scoping proximity between the scoping root and the subject of the scoped selector.

Should this have the same scope proximity weighting as @scope or different scope proximity weighting (or no scope proximity weighting)?

For example, these three selectors will all select the same elements, with the same specificity:
(.ancestor) .child                { color: darkmagenta; }
.child:is(.ancestor, .ancestor *) { color: darkmagenta; }
.ancestor.child, .ancestor .child { color: darkmagenta; }

However the first rule will win, because it also applies weak scoping proximity.

How does this interact with [CSS-NESTING-1]?

This notation was added in order to allow scoping limits to be applied within querySelector(). Is this something we want to have?

2.6. Precedence of Non-CSS Presentational Hints

CSS Cascading 5 § 6.4 Cascade Layers

3. Changes

3.1. Additions Since Level 5

The following features have been added since Level 5:

3.2. Additions Since Level 4

The following features have been added since Level 4:

3.3. Additions Since Level 3

The following features have been added since Level 3:

3.4. Additions Since Level 2

The following features have been added since Level 2:

Acknowledgments

David Baron, Tantek Çelik, Florian Rivoal, Simon Sapin, Jen Simmons, Giuseppe Gurgone, Keith Grant, Lea Verou, Nicole Sullivan, Theresa O’Connor, and Boris Zbarsky contributed to this specification.

Privacy and Security Considerations

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Tests

Tests relating to the content of this specification may be documented in “Tests” blocks like this one. Any such block is non-normative.


Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-ANIMATIONS-1]
Dean Jackson; et al. CSS Animations Level 1. 11 October 2018. WD. URL: https://www.w3.org/TR/css-animations-1/
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. 15 October 2021. WD. URL: https://www.w3.org/TR/css-cascade-5/
[CSS-COLOR-5]
Chris Lilley; et al. CSS Color Module Level 5. 22 July 2021. WD. URL: https://www.w3.org/TR/css-color-5/
[CSS-CONDITIONAL-4]
David Baron. CSS Conditional Rules Module Level 4. 3 March 2020. WD. URL: https://www.w3.org/TR/css-conditional-4/
[CSS-SCOPING-1]
Tab Atkins Jr.; Elika Etemad. CSS Scoping Module Level 1. 3 April 2014. WD. URL: https://www.w3.org/TR/css-scoping-1/
[CSS-SYNTAX-3]
Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. 16 July 2019. CR. URL: https://www.w3.org/TR/css-syntax-3/
[CSS-TRANSITIONS-1]
David Baron; et al. CSS Transitions. 11 October 2018. WD. URL: https://www.w3.org/TR/css-transitions-1/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 6 June 2019. CR. URL: https://www.w3.org/TR/css-values-3/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SELECT]
Tantek Çelik; et al. Selectors Level 3. 6 November 2018. REC. URL: https://www.w3.org/TR/selectors-3/
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 21 November 2018. WD. URL: https://www.w3.org/TR/selectors-4/

Informative References

[CSS-COLOR-4]
Tab Atkins Jr.; Chris Lilley. CSS Color Module Level 4. 1 June 2021. WD. URL: https://www.w3.org/TR/css-color-4/
[CSS-NESTING-1]
Tab Atkins Jr.; Adam Argyle. CSS Nesting Module. 31 August 2021. WD. URL: https://www.w3.org/TR/css-nesting-1/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/

Issues Index

This is a diff spec over CSS Cascading and Inheritance Level 5. It is currently an Exploratory Working Draft: if you are implementing anything, please use Level 5 as a reference. We will merge the Level 5 text into this draft once it reaches CR.
Does scope proximity belong above or below specificity in the cascade?
CSS Cascading 5 § 6.2 Cascading Origins
CSS Cascading 5 § 6.3 Important Declarations: the !important annotation
CSS Cascading 5 § 6.4 Cascade Layers
Inclusive vs exclusive scope boundaries [Issue #6577]
Should scoping limits be added to the definition of scoped selectors?
Should @scope use strong or weak scoping proximity? Strong scoping proximity causes declarations to be weighted more strongly by scope proximity than by their selector’s specificity. Weak scoping proximity causes declarations of the same specificity to be weighted by proximity to their scoping root before falling back to source ordering, but declarations of higher specificity win over more tightly-scoped declarations.
Should the scoped descendant combinator use strong or weak scoping proximity? Should it even exist? It’s defined here to work the way many people expected the regular descendant combinator to work...
Should this have the same scope proximity weighting as @scope or different scope proximity weighting (or no scope proximity weighting)?
How does this interact with [CSS-NESTING-1]?
This notation was added in order to allow scoping limits to be applied within querySelector(). Is this something we want to have?
CSS Cascading 5 § 6.4 Cascade Layers