CSS Cascading and Inheritance Level 5

If a property does not apply to this element or box type then it has no used value for that property.

For example, the flex property has no used value on elements that aren’t flex items.

4.5.1. Applicable Properties

If a property does not apply to an element or box type—as noted in its “Applies to” line—this means it does not directly take effect on that type of box or element.

Note: A property that does not apply can still have indirect formatting effects if its computed value affects the computation of other properties that do apply; and of course its computed value, which always exists, can still inherit to descendants and take effect on them.

Note: A property defined to apply to “all elements” applies to all elements and display types, but not necessarily to all pseudo-element types, since pseudo-elements often have their own specific rendering models or other restrictions. The ::before and ::after pseudo-elements, however, are defined to generate boxes almost exactly like normal elements and are therefore defined accept all properties that apply to “all elements”. See [CSS-PSEUDO-4] for more information about pseudo-elements.

4.6. Actual Values

A used value is in principle ready to be used, but a user agent may not be able to make use of the value in a given environment. For example, a user agent may only be able to render borders with integer pixel widths and may therefore have to approximate the used width. Also, the font size of an element may need adjustment based on the availability of fonts or the value of the font-size-adjust property. The actual value is the used value after any such adjustments have been made.

Note: By probing the actual values of elements, much can be learned about how the document is laid out. However, not all information is recorded in the actual values. For example, the actual value of the page-break-after property does not reflect whether there is a page break or not after the element. Similarly, the actual value of orphans does not reflect how many orphan lines there is in a certain element. See examples (j) and (k) in the table below.

4.7. Examples

4.8. Per-Fragment Value Processing

Certain CSS features can interfere with value processing on a per-fragment basis. See for example CSS Pseudo-Elements 4 § 2.1.3 Inheritance and the ::first-line Pseudo-element which alters inheritance for fragments within the ::first-line pseudo-element. In such cases, where individual fragments are given different specified values, any values that resolve based on the computed value of other properties (such as currentcolor or em units) are resolved per box fragment. Subsequent value processing proceeds as normal in each fragment.

APIs that assume a singular value per box (rather than per box fragment) must ignore the effects of non-tree-abiding pseudo-elements. (For example, ::first-line styles have no effect on the value returned by getComputedStyle().)

<div><span>First line<br />Second linespan>div>
<div><span>First linespan>div>
<div>First line<br><span>Second linespan>div>
<style>
div { color: blue; }
div::first-line { color: yellow; }
span { border: thin solid currentcolor; }
style>

5. Filtering

In order to find the declared values, implementations must first identify all declarations that apply to each element. A declaration applies to an element if:

• It belongs to a style sheet that currently applies to this document.
• It is not qualified by a conditional rule [CSS-CONDITIONAL-3] with a false condition.
• It belongs to a style rule whose selector matches the element. [SELECT] (Taking scoping into account, if necessary.)
• It is syntactically valid: the declaration’s property is a known property name, and the declaration’s value matches the syntax for that property.

The values of the declarations that apply form, for each property on each element, a list of declared values. The next section, the cascade, prioritizes these lists.

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

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

Element-Attached Styles

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.

See [css-style-attr].

Note: Non-CSS presentational hints (such as presentational markup) are handled separately, see § 6.5 Precedence of Non-CSS Presentational Hints.

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.

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.

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.

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

6.2. Cascading Origins

Each style rule has a cascade origin, which determines where it enters the cascade. CSS defines three core origins:

Author Origin

The author specifies style sheets for a source document according to the conventions of the document language. For instance, in HTML, style sheets may be included in the document or linked externally.

User Origin

The user may be able to specify style information for a particular document. For example, the user may specify a file that contains a style sheet or the user agent may provide an interface that generates a user style sheet (or behaves as if it did).

User-Agent Origin

Conforming user agents must apply a default style sheet (or behave as if they did). A user agent’s default style sheet should present the elements of the document language in ways that satisfy general presentation expectations for the document language (e.g., for visual browsers, the EM element in HTML is presented using an italic font). See e.g. the HTML user agent style sheet. [HTML]

Extensions to CSS define the following additional origins:

Animation Origin

CSS Animations [css-animations-1] generate “virtual” rules representing their effects when running.

Transition Origin

Like CSS Animations, CSS Transitions [css-transitions-1] generate “virtual” rules representing their effects when running.

6.3. Important Declarations: the !important annotation

CSS attempts to create a balance of power between author and user style sheets. By default, rules in an author’s style sheet override those in a user’s style sheet, which override those in the user-agent’s default style sheet. To balance this, a declaration can be marked important, which increases its weight in the cascade and inverts the order of precedence.

A declaration is important if it has a !important annotation as defined by [css-syntax-3], i.e. if the last two (non-whitespace, non-comment) tokens in its value are the delimiter token ! followed by the identifier token important. All other declarations are normal (non-important).

[hidden] { display: none !important; }

An important declaration takes precedence over a normal declaration. Author and user style sheets may contain important declarations, with user-origin important declarations overriding author-origin important declarations. This CSS feature improves accessibility of documents by giving users with special requirements (large fonts, color combinations, etc.) control over presentation.

Important declarations from all origins take precedence over animations. This allows authors to override animated values in important cases. (Animated values normally override all other rules.) [css-animations-1]

User-agent style sheets may also contain important declarations. These override all author and user declarations.

/* From the user’s style sheet */
p { text-indent: 1em !important }
p { font-style: italic !important }
p { font-size: 18pt }

/* From the author’s style sheet */
p { text-indent: 1.5em !important }
p { font: normal 12pt sans-serif !important }
p { font-size: 24pt }

6.4. Cascade Layers

In the same way that cascade origins provide a balance of power between user and author styles, cascade layers provide a structured way to organize and balance concerns within a single origin. Rules within a single cascade layer cascade together, without interleaving with style rules outside the layer.

Authors can create layers to represent element defaults, third-party libraries, themes, components, overrides, and other styling concerns—and are able to re-order the cascade of layers in an explicit way, without altering selectors or specificity within each layer, or relying on source-order to resolve conflicts across layers.

audio {
  /* specificity of 0,0,1 - implicit (final) layer */
  display: flex;
}

@layer reset {
  audio[controls] {
    /* specificity of 0,1,1 - explicit "reset" layer */
    display: block;
  }
}

Name-defining at-rules such as @keyframes or @font-face that are defined inside cascade layers also use the layer order when resolving name collisions.

/* establish the layer order, so the "override" layer takes precedence */
@layer framework, override;

@layer override {
  @keyframes slide-left {
    from { translate: 0; }
    to { translate: -100% 0; }
  }
}

@layer framework {
  @keyframes slide-left {
    from { margin-left: 0; }
    to { margin-left: -100%; }
  }
}

.sidebar { animation: slide-left 300ms; }

6.4.1. Declaring Cascade Layers

Cascade layers can be declared:

• using an @import rule with the layer keyword or layer() function, assigning the contents of the imported file into that layer.

• using a @layer block at-rule, assigning its child style rules into that layer.

• using a @layer statement at-rule, declaring a named layer without assigning any rules.

Provide an attribute for assigning link or style elements to cascade layers? [Issue #w3c/csswg-drafts#5853]

6.4.2. Layer Naming and Nesting

A cascade layer has a layer name, which is an ordered list representing each level of layer nesting, each segment of which can be named (as a CSS identifier) or anonymous. (Thus, when a layer is nested inside of another layer, this concatenates their names.) One layer is nested in another when it is declared within the scope of another layer, e.g. an @layer rule inside another @layer, a layered @import inside a layered import, or an @layer rule inside a layered import.

Layer names represent the same cascade layer if they contain the same segments in the same order; however anonymous segments have unique identities for each occurrence. Note that nesting can cause multiple layers to share the same anonymous segment.

@import url(headings.css) layer(default);
@import url(links.css) layer(default);

@layer default {
  audio[controls] {
    display: block;
  }
}

@layer base {
  p { max-width: 70ch; }
}

@layer framework {
  @layer base {
    p { margin-block: 0.75em; }
  }

  @layer theme {
    p { color: #222; }
  }
}

Syntactically, an explicit layer name is represented by the in @layer and @import rules, which is a period-separated list of tokens with no intervening white space:

 =  [ '.'  ]*

The CSS-wide keywords are reserved for future use, and cause the rule to be invalid at parse time if used as an in the . When multiple identifiers are concatenated with a period, this is a shorthand representing those layers nested in order.

@layer framework {
  @layer default {
     p { margin-block: 0.75em; }
  }

  @layer theme {
    p { color: #222; }
  }
}

@layer framework.theme {
  /* These styles will be added to the theme layer inside the framework layer */
  blockquote { color: rebeccapurple; }
}

Note: A nested layer cannot “escape” its parent layer to reference layers outside itself.

6.4.2.1. Anonymous Layers

When a @layer rule omits its , or an @import rule uses the layer keyword (which does not provide a ), its layer name gains a unique anonymous segment; it therefore cannot be referenced from the outside.

/* bootstrap-base.css */
/* unnamed wrapper layers around each sub-file */
@import url(base-forms.css) layer;
@import url(base-links.css) layer;
@import url(base-headings.css) layer;

/* bootstrap.css */
/* the internal names are hidden from access, subsumed in "base" */
@import url(bootstrap-base.css) layer(base);

/* author.css */
/* author has access to bootstrap.base layer, but not into unnamed layers */
@import url(bootstrap.css) layer(bootstrap);

/* Adds additional styles to the bootstrap layer: */
@layer bootstrap {...}

6.4.3. Layer Ordering

Cascade layers are sorted by the order in which they first are declared, with nested layers grouped within their parent layers before any unlayered rules.

/* unlayered styles come last in the layer order */
h1 { color: darkslateblue; }

@layer reset.type {
  strong { font-weight: bold; }
}

@layer framework {
  .title { font-weight: 100; }

  @layer theme {
    h1, h2 { color: maroon; }
  }
}

@layer reset {
  [hidden] { display: none; }
}

Layers that are defined inside of a conditional group rule do not contribute to the layer order unless the condition is true or unless the conditional group rule can evaluate differently for different elements in the document.

Note: Since the layer order is global to the document, any layers defined inside an element-sensitive conditional group rule need to be accommodated when establishing the global layer order, regardless of the rule’s condition. Conditions that are global to the document, however (such as @media and @supports) can accommodate such @layer rules conditionally.

@media (min-width: 30em) {
  @layer layout {
    .title { font-size: x-large; }
  }
}

@media (prefers-color-scheme: dark) {
  @layer theme {
    .title { color: white; }
  }
}

@layer theme, layout;

Note: Cascade layers are scoped to their origin and context, so the ordering of layers in the light DOM has no impact on the order of identically-named layers in the shadow DOM (and vice versa).

Allow authors to explicitly place unlayered styles in the layer order [Issue #6323]

6.4.4. Declaring Layers Inline: the @layer rule

The @layer rule declares a cascade layer, with the option to assign style rules.

6.4.4.1. Assigning Styles Inline: the @layer block at-rule

The @layer block at-rule assigns its child style rules to a particular named cascade layer. This block layer-assignment syntax is:

@layer ? {
  
}

Such @layer block rules have the same restrictions and processing as a conditional group rule [CSS-CONDITIONAL-3] with a true condition.

@layer framework {
  h1, h2 { color: maroon; background: white;}

  @media (prefers-color-scheme: dark) {
    h1, h2 { color: red; background: black; }
  }
}

Note: @layer block at-rules cannot be interleaved with @import rules.

6.4.4.2. Declaring Without Styles: the @layer statement at-rule

The @layer rule can also be used to define new layers without assigning any style rules, by providing only the layer name:

@layer #;

Such empty @layer rules are allowed before @import and @namespace rules (after the @charset rule, if any) as well as everywhere @layer block at-rules are allowed.

Note: No @layer rules are allowed between @import and @namespace rules. Any @layer rule that comes after an @import or @namespace rule will cause any subsequent @import or @namespace rules to be ignored.

Unlike the block syntax, multiple comma-separated layer names can be provided in this syntax, declaring each of the layers in the order specified.

Note: Since layer ordering is defined by first occurrence of the layer name (see § 6.4.3 Layer Ordering), this rule allows a page to declare the order of its layers up front, so that their order is apparent without having to read the entire style sheet. It also allows inline layers to be interleaved with imported layers, which is not possible with the block syntax.

@layer default, theme, components;
@import url(theme.css) layer(theme);

@layer default {
  audio[controls] {
    display: block;
  }
}

@layer default;
@import url(theme.css) layer(theme);
@layer components;

@layer default {
  audio[controls] {
    display: block;
  }
}

@import url(default.css) layer(default);
@layer theme;
@import url(components.css) layer(components);

@layer theme {
  audio[controls] {
    display: block;
  }
}

6.5. Precedence of Non-CSS Presentational Hints

The UA may choose to honor presentational hints in a source document’s markup, for example the bgcolor attribute or s element in [HTML]. All document language-based styling must be translated to corresponding CSS rules and enter the cascade as rules in either the UA-origin or a special-purpose author presentational hint origin between the regular user origin and the author origin. For the purpose of cascading this author presentational hint origin is treated as an independent origin, but for the purpose of the revert keyword it is considered part of the author origin.

A document language may define whether such a presentational hint enters the cascade as UA-origin or author-origin; if so, the UA must behave accordingly. For example, [SVG11] maps its presentation attributes into the author origin.

Note: Presentational hints entering the cascade as UA-origin rules can be overridden by author-origin or user-origin styles. Presentational hints entering the cascade as author presentational hint origin rules can be overridden by author-origin styles, but not by non-important user-origin styles. Host languages should choose the appropriate origin for presentational hints with these considerations in mind.

7. Defaulting

When the cascade does not result in a value, the specified value must be found some other way. Inherited properties draw their defaults from their parent element through inheritance; all other properties take their initial value. Authors can explicitly request inheritance or initialization via the inherit and initial keywords.

7.1. Initial Values

Each property has an initial value, defined in the property’s definition table. If the property is not an inherited property, and the cascade does not result in a value, then the specified value of the property is its initial value.

7.2. Inheritance

Inheritance propagates property values from parent elements to their children. The inherited value of a property on an element is the computed value of the property on the element’s parent element. For the root element, which has no parent element, the inherited value is the initial value of the property.

For a [DOM] tree with shadows, inheritance operates on the flattened element tree. This means that slotted elements inherit from the slot they’re assigned to, rather than directly from their light tree parent. Pseudo-elements inherit according to the fictional tag sequence described for each pseudo-element. [CSS-PSEUDO-4]

Some properties are inherited properties, as defined in their property definition table. This means that, unless the cascade results in a value, the value will be determined by inheritance.

A property can also be explicitly inherited. See the inherit keyword.

Note: Inheritance follows the document tree and is not intercepted by anonymous boxes, or otherwise affected by manipulations of the box tree.

7.3. Explicit Defaulting

Several CSS-wide property values are defined below; declaring a property to have these values explicitly specifies a particular defaulting behavior. As specified in CSS Values and Units [css-values-3], all CSS properties can accept these values.

7.3.1. Resetting a Property: the initial keyword

If the cascaded value of a property is the initial keyword, the property’s specified value is its initial value.

7.3.2. Explicit Inheritance: the inherit keyword

If the cascaded value of a property is the inherit keyword, the property’s specified and computed values are the inherited value.

7.3.3. Erasing All Declarations: the unset keyword

If the cascaded value of a property is the unset keyword, then if it is an inherited property, this is treated as inherit, and if it is not, this is treated as initial. This keyword effectively erases all declared values occurring earlier in the cascade, correctly inheriting or not as appropriate for the property (or all longhands of a shorthand).

7.3.4. Rolling Back Cascade Origins: the revert keyword

If the cascaded value of a property is the revert keyword, the behavior depends on the cascade origin to which the declaration belongs:

user-agent origin

Equivalent to unset.

user origin

Rolls back the cascaded value to the user-agent level, so that the specified value is calculated as if no author-origin or user-origin rules were specified for this property on this element.

author origin

Rolls back the cascaded value to the user level, so that the specified value is calculated as if no author-origin rules were specified for this property on this element. For the purpose of revert, this origin includes the Animation origin.

7.3.5. Rolling Back Cascade Layers: the revert-layer keyword

If the cascaded value of a property is the revert-layer keyword, the cascaded value is rolled back to the layer below, so that the specified value is calculated as if no rules were specified in the current cascade layer—or between its normal and important levels in the cascade—for this property on this element. For revert-layer in important element-attached styles, however, it only reverts the element-attached styles and the intervening animation origin, and not any of the intervening author-origin important rules.

Note: If there are no lower-priority declarations in the same cascade origin as the revert-layer value, the cascaded value will roll back to the previous origin.

Note: The animation origin is not collapsed with the author origin for this purpose as it is for revert, and thus effectively forms its own cascade layer.

8. Layer APIs

8.1. Extensions to the CSSImportRule interface

The CSSImportRule interface is extended as follows:

partial interface CSSImportRule {
  readonly attribute CSSOMString? layerName;
};

Its layerName attribute represents the layer name declared in the at-rule itself, and is an empty string if the layer is anonymous, or null if the at-rule does not declare a layer.

8.2. The CSSLayerBlockRule interface

The CSSLayerBlockRule interface represents the @layer block rule:

[Exposed=Window]
interface CSSLayerBlockRule : CSSGroupingRule {
  readonly attribute CSSOMString name;
};

Its name attribute represents the layer name declared by the at-rule itself, and is an empty string if the layer is anonymous.

@layer outer {
  @layer foo.bar { }
}

8.3. The CSSLayerStatementRule interface

The CSSLayerStatementRule interface represents the @layer statement:

[Exposed=Window]
interface CSSLayerStatementRule : CSSRule {
  readonly attribute FrozenArray<CSSOMString> nameList;
};

Its nameList attribute represents the list of layer names declared by the at-rule, normalized following the same rule as the CSSLayerBlockRule’s name attribute.

9. Changes

9.1. Changes since the 15 Oct 2021 Working Draft

Non-trivial changes since the 15 October 2021 Working Draft:

• Updated grammar style for @import media queries and supports conditions

• Allowed functional notation parse-time aliases (Issue 6193)

• Made CSSImportRule.layerName nullable (Issue 6576)

• Clarified that revert-layer in style attr does not revert author layers (Issue 6743)

• Clarified revert-layer on style attr and keyframes (Issue 6743)

• Added § 4.1.1 Value Aliasing section. (Issue 6193)

• Added § 8 Layer APIs section. (Issue 6576)

• Clarified the behavior of revert-layer keyword when used in the style attribute or @keyframes at-rule. (Issue 6743)

• Clarified the behavior of the layer keyword and layer() function on @import rules. (Issue 6776)

9.2. Changes since the 29 August 2021 Working Draft

Changes since the 29 August 2021 Working Draft include:

• Revert the ordering of unlayered styles. (See § 9.3 Changes since the 8 June 2021 Working Draft and Issue 6284)

• Defined presentational hints to use the author presentational hint origin instead of layers, matching update to [CSS-CASCADE-4]. (Issue 6659)

9.3. Changes since the 8 June 2021 Working Draft

Significant changes since the 8 June 2021 Working Draft include:

• Reserve the CSS-wide keywords for future use in layer-names. (Issue 6323)

• Clarify that @layer rules respect global conditional rules, but are always applied to the layer order when declared in non-global conditions such as a container query. (Issue 6407)

• Name-defining at-rules follow layer order for collision resolution, similar to specificity resolution. (Issue 6404)

• Disallow interleaving of @layer with @import or @namespace rules. (Issue 6522)

9.4. Changes since the 19 March 2021 Working Draft

Significant changes since the 19 March 2021 Working Draft include:

• Switched the ordering of unlayered styles from highest to lowest priority in the normal origins. (Issue 6284)

9.5. Changes since the 19 January 2021 Working Draft

Significant changes since the 19 January 2021 First Public Working Draft include:

• Switched layer import syntax from using @layer to using @import. (Issue 5681)

• Added revert-layer keyword. (Issue 5793)

9.6. Additions Since Level 4

The following features have been added since Level 4:

• Added cascade layers to the cascade sort criteria (and defined style attributes as a distinct step of the cascade sort criteria so that they interact appropriately).

• Introduced the @layer rule for defining cascade layers.

• Added layer/layer() option to @import definition.

• Introduced the revert-layer keyword for rolling back values to previous layers.

9.7. Additions Since Level 3

The following features have been added since Level 3:

• Introduced revert keyword, for rolling back the cascade.

• Introduced supports() syntax for supports-conditional @import rules.

• Added encapsulation context to the cascade sort criteria to accommodate Shadow DOM. [DOM]

• Defined the property two aliasing mechanisms CSS uses to support legacy syntaxes. See § 3.1 Property Aliasing.

9.8. Additions Since Level 2

The following features have been added since Level 2:

• The all shorthand
• The initial keyword
• The unset keyword
• Incorporation of animations and transitions into the cascade.

Acknowledgments

David Baron, Tantek Çelik, Florian Rivoal, Simon Sapin, Jen Simmons, and Boris Zbarsky contributed to this specification.

Privacy and Security Considerations

• The cascade process does not distinguish between same-origin and cross-origin stylesheets, enabling the content of cross-origin stylesheets to be inferred from the computed styles they apply to a document.

• User preferences and UA defaults expressed via application of style rules are exposed by the cascade process, and can be inferred from the computed styles they apply to a document.

• The @import rule does not apply the CORS protocol to loading cross-origin stylesheets, instead allowing them to be freely imported and applied.

• The @import rule assumes that resources without Content-Type metadata (or any same-origin file if the host document is in quirks mode) are text/css, potentially allowing arbitrary files to be imported into the page and interpreted as CSS, potentially allowing sensitive data to be inferred from the computed styles they apply to a document.