CSS at-ruleAt-rules

@layer

Splits styles into cascade layers with a fixed order. A rule from a later layer wins regardless of selector specificity.

On this page

Example

#
CSS
@layer reset, base, components, utilities;

@layer reset {
  button { margin: 0; border: 0; font: inherit; }
}

@layer base {
  a { color: #a78bfa; }
}

@layer components {
  button.btn {
    padding: 8px 16px;
    border-radius: 10px;
    background: #7c3aed;
    color: #fff;
  }
}

@layer utilities {
  .bg-rose { background: #f43f5e; }
}
Preview

The helper class .bg-rose beats button.btn even though it has lower specificity, because the utilities layer is last in the list.

Definition and usage

#

The @layer rule organizes the cascade. You wrap styles in named layers, and which declaration wins is decided first by the order of the layers, and only then by selector specificity and position in the code. A #menu .link selector from an earlier layer loses to a plain a from a later layer.

The order is set by the first appearance of a name. It is easiest to write it once, at the start of the stylesheet: @layer reset, base, components, utilities;. After that you can add styles to layers anywhere and in any order, even in separate files, e.g. through @import url("reset.css") layer(reset).

Styles written outside any layer form an implicit layer that comes last, so they beat all layers. This is intentional: existing code keeps working, and you can introduce layers gradually. With !important the order reverses: an important declaration from the first layer beats important declarations from later layers.

A popular setup has four layers: reset zeroes out the browser’s default styles, base sets typography and the look of plain HTML elements, components holds buttons, cards, and forms, and utilities small helper classes that should always win. Tailwind CSS version 4 uses a similar split.

Syntax

#
Syntax
@layer reset, base, components;

@layer components {
  selector { property: value; }
}

How layers win

#
  • layer order

    theme, green

    The theme layer is second in the list, so it wins, even though its block sits higher in the code than the base block.
  • stronger selector

    theme, green

    In base there is a selector with an ID, and it still loses. Layers are compared before specificity.
  • unlayered style

    unlayered style, amber

    A rule outside layers beats any layer, even when it has a weaker selector and comes earlier in the code.
  • !important

    base, red

    With !important the order reverses: an important declaration from an earlier layer beats an important one from a later layer. This lets a reset protect key styles.
  • nested layers

    components.buttons, sky blue

    Layers can be nested, and you refer to an inner one with a dot. The order then counts within the components group.
  • revert-layer

    back to base on hover

    The revert-layer keyword rolls the value back to the one from earlier layers. Hover over the button: it returns to the green background from the base layer.

How layers win in practice

#

layer order

The theme layer is second in the list, so it wins, even though its block sits higher in the code than the base block.
@layer base, theme;

@layer theme {
  .demo { background: #10b981; }
}

@layer base {
  .demo { background: #f43f5e; }
}

stronger selector

In base there is a selector with an ID, and it still loses. Layers are compared before specificity.
@layer base, theme;

@layer base {
  #cta.demo { background: #f43f5e; }
}

@layer theme {
  .demo { background: #10b981; }
}

unlayered style

A rule outside layers beats any layer, even when it has a weaker selector and comes earlier in the code.
button { background: #f59e0b; }

@layer theme {
  #cta.demo { background: #10b981; }
}

!important

With !important the order reverses: an important declaration from an earlier layer beats an important one from a later layer. This lets a reset protect key styles.
@layer base, theme;

@layer base {
  .demo { background: #f43f5e !important; }
}

@layer theme {
  .demo { background: #10b981 !important; }
}

nested layers

Layers can be nested, and you refer to an inner one with a dot. The order then counts within the components group.
@layer components.base, components.buttons;

@layer components.buttons {
  .demo { background: #0ea5e9; }
}

@layer components.base {
  .demo { background: #f43f5e; }
}

revert-layer

The revert-layer keyword rolls the value back to the one from earlier layers. Hover over the button: it returns to the green background from the base layer.
@layer base, theme;

@layer base {
  .demo { background: #10b981; }
}

@layer theme {
  .demo { background: #f43f5e; }
  .demo:hover { background: revert-layer; }
}

More examples

#
A library style in a layer loses to your code
CSS
@layer vendor, app;

@layer vendor {
  #widget .title { color: #f43f5e; }
}

@layer app {
  .title { color: #10b981; }
}
Preview

The library’s selector contains an ID and still loses, because the vendor layer comes earlier. In practice you would load the library into a layer with @import url("lib.css") layer(vendor).

Browser support

#

Widely available · since 2022

Works in all modern browsers, phones included. You can use it without worry.

  • Chrome
  • Edge
  • Firefox
  • Safari

Good practices

#
  • Write the order of all layers on a single line at the very start of the stylesheet. The order is set by the first occurrence of a name, so without that line it is easy to change it by accident.
  • Remember that styles outside layers beat layers. When migrating old code, start with the reset and libraries, and for now leave your own styles outside layers.
  • Layers replace the specificity race. Instead of adding more classes and !important, move the rule to a later layer.

Related entries

#

Practise it in lessons

#

Spotted a mistake or missing an example? Write to us.