ZipKit
Glossary

CSS cascade

CSS cascade is the algorithm that chooses a single winning declaration for each property on each element when several rules compete. It is defined in the W3C CSS Cascading and Inheritance module, and Level 5 added cascade layers. The part people search for is the sort order: origin and importance, context, element-attached styles, layers, specificity, then order of appearance.

How it works

The cascade compares two declarations one criterion at a time and stops at the first criterion that differs. Level 5 lists them in descending priority:

  • Origin and importance: from strongest to weakest, transition declarations, important user-agent, important user, important author, animations, normal author, normal user, normal user-agent.
  • Context: for normal rules the outer shadow tree wins, for important rules the inner one wins.
  • Element-attached styles: a style attribute beats rules of the same importance.
  • Layers: for normal rules the last layer wins, for important rules the first layer wins. Unlayered styles count as an implicit final layer.
  • Specificity: the higher selector weight wins.
  • Order of appearance: the last declaration in document order wins.

The cascade produces the cascaded value. Defaulting then gives the specified value, and resolving relative values gives the computed value. Inheritance happens in the defaulting step, only when the cascade produced no value.

@layer base, theme;
@layer base  { #x.y.y { color: red; } }
@layer theme { p      { color: green; } }

Computed color of <p id="x" class="y"> in headless Chromium 141:

rgb(0, 128, 0)

The red rule has specificity (1,2,0) against (0,0,1), but theme was declared after base, so layer order decides before specificity is read.

Does a declaration marked important always win?

No, it only wins inside its own bucket. An important author declaration beats a normal one, but an important user-agent or user declaration beats it. Inside layers the order flips. With base declared before theme and color marked important in both, plus an important unlayered rule, the winner in Chromium 141 was the base rule, rgb(255, 0, 0). The first layer wins for important rules, and important layered rules beat important unlayered ones.

What does the revert keyword do?

It rolls the value back to the previous origin. In an author rule, revert discards author declarations for that property and uses the user or user-agent value. revert-layer rolls back only to the layer below.

Common pitfalls

  • Unlayered CSS beats every layer: a library placed in @layer loses to your plain stylesheet whatever its selectors say. That is by design, and it is the main reason to layer third-party CSS.
  • Reversed layer order for important rules: a team that puts resets in the first layer and marks resets !important will find the resets override everything later.
  • Assuming a later file always wins: order of appearance is the last tiebreaker. A link tag that loads later loses to an earlier rule with a higher origin, layer or specificity.
  • Fighting the user agent: a links stay blue because the user-agent sheet sets a:link, and an inherited color on a parent never reaches them.
  • Confusing the cascaded and computed value: getComputedStyle returns computed or used values, not the declaration that won.

Related terms

  • CSS specificity — the fifth sort criterion in the cascade
  • CSS inheritance — what supplies a value when the cascade produces none
  • CSS pseudo-class — adds to specificity and so changes who wins
  • DOM — the tree whose elements the cascade runs over, including shadow trees

See also