How CSS revert-layer Works in Cascade Layers

The CSS revert-layer keyword allows developers to step backward through the cascade hierarchy, rolling a property's value back to the declaration set in the previous cascade layer. This article explains the evaluation order of cascade layers, how revert-layer determines which value to apply next, and how its behavior distinctively differs from other reset keywords like revert and unset.

The Role of Cascade Layers

CSS Cascade Layers (@layer) establish an explicit priority order for author styles, independent of selector specificity. Layers defined later in the stylesheet take precedence over layers defined earlier. Outside of these, unlayered author styles maintain the highest priority over all layered author styles.

@layer base, theme, components;

In this order, rules inside components override matching rules inside theme, which in turn override base.

How revert-layer Evaluates Values

When revert-layer is assigned to a CSS property, the browser ignores the current layer's declaration for that property and searches for the next winning value as if the current layer does not declare it.

The evaluation follows this precise path:

1. Previous Author Layers: The browser inspects the layer immediately preceding the current one in the layer order. If a matching rule exists there, that value is applied.
2. Next Preceding Layers: If no match exists in the immediate predecessor, the browser continues moving backward through earlier author layers until a match is found.
3. Implicit Layer / Other Origins: If the keyword is invoked in the lowest-priority author layer (or if no previous author layer matches the selector), the property rolls back to matching declarations in subsequent origins:
   • The user style sheet (if present).
   • The user-agent style sheet (browser default styles).
4. Unlayered Styles: If revert-layer is used inside an unlayered author rule, it rolls back the property to the highest-priority declared @layer.

Practical Example

Consider the following cascade configuration:

@layer base {
  p {
    color: red;
  }
}

@layer theme {
  p {
    color: blue;
  }
}

@layer components {
  p.alert {
    color: revert-layer;
  }
}

When evaluating a <p class="alert">:

1. The browser checks components. It sees color: revert-layer.
2. It steps back to the theme layer and finds p { color: blue; }.
3. The computed color becomes blue.
4. If theme had no declaration for p, the browser would continue back to base and resolve to red.

revert-layer vs. revert

While both keywords roll back values, their scopes are different:

• revert discards all author-level styles entirely for that declaration, rolling back directly to the user or user-agent style sheet regardless of any other cascade layers defined by the author.
• revert-layer only steps out of the current layer. It preserves matching declarations from lower-priority layers within the same author origin before falling back to user or user-agent defaults.