Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 139 ยท The Cascade

Cascade Layers

Use @layer to control which CSS wins by layer instead of specificity. Learn layer order, unlayered styles, !important, nesting and importing CSS into layers.

Specificity was designed for single stylesheets. Real projects combine a reset, a framework, component styles, page tweaks and utility classes, often written by different people. Getting all of those to win and lose in the right order with specificity alone is a constant battle: the framework uses a heavy selector, so you write a heavier one, and so on.

Cascade layers fix this at the source. With the @layer rule you sort your CSS into named layers and state, once, which layer beats which. Between layers, the layer order decides and specificity doesn't matter at all. In this lesson you will learn how to create layers, how they fit into the cascade, and how to organize a real stylesheet with them.

Support: cascade layers work in all modern browsers (Chrome and Edge 99+, Firefox 97+, Safari 15.4+, all from early 2022). They are safe to use on any site that doesn't need to support much older browsers.

Your first layers

Put rules inside an @layer block with a name. The order in which layers are first mentioned is their order of priority: the later a layer, the stronger it is.

A later layer beats a more specific selector

Without layers, #page .content p would beat .highlight easily. With layers, the cascade compares layers before specificity, and components comes after base, so it wins. Specificity is still used, but only to settle conflicts inside the same layer.

Declaring the order up front

Relying on "first mentioned" is fragile, because the order can change when files are reordered. Instead, declare all your layers at the top with a single statement:

CSS
@layer reset, base, components, utilities;

This statement creates four empty layers in that order. Later @layer blocks with the same names add rules to the existing layers; they don't change the order. You can add to a layer as many times as you like, in any file.

The order statement controls priority

The utilities block comes first in the file, yet utilities still beat components, because the order statement mentioned utilities last. Try changing the statement to @layer reset, utilities, components; and the utilities stop working.

Unlayered styles beat all layers

Any CSS that is not inside a layer belongs to an implicit, unlayered group. For normal declarations, unlayered styles are stronger than every layer, as if they were in a final layer after all the others.

Unlayered beats layered

This is great news when you use third-party CSS. Put the library in a layer and every one of your ordinary, unlayered rules overrides it, without any specificity tricks. It also means that adopting layers is gradual: existing unlayered CSS keeps working and stays on top while you move things into layers.

This surprises people. If you put your own code in layers but leave a library unlayered, the library will beat all of your layered code. When you use layers, layer the things you want to be weaker.

Layers and !important

For !important declarations, the layer order is reversed:

  • Normal declarations: later layers win, and unlayered styles beat all layers.
  • Important declarations: earlier layers win, and important declarations in any layer beat important unlayered ones.

So with @layer reset, components;, an important declaration in reset beats an important one in components, which beats an important unlayered one. This lets an early layer, such as a reset or an accessibility layer, mark a few declarations as non-negotiable without later layers overriding them by accident. The !important lesson has a live example. In practice, if your layers are well organized you rarely need !important at all.

Importing CSS into a layer

You can place a whole stylesheet into a layer as you import it:

CSS
@layer reset, vendor, components;

@import url("reset.css") layer(reset);
@import url("datepicker.css") layer(vendor);

Remember that @import rules must come before any other rules in a stylesheet (only @charset and @layer statements may come before them). That is why the order statement goes first and the imports follow.

Writing layer without a name, as in @import url("x.css") layer;, puts the file into an anonymous layer. Anonymous layers work, but you can never add to them or refer to them later, so named layers are usually clearer.

On <link> elements: browsers do not yet support putting a linked stylesheet into a layer with an HTML attribute. Use @import ... layer() inside a CSS file, or wrap the CSS in an @layer block yourself.

Nested layers

Layers can contain other layers. Refer to a nested layer with a dot:

CSS
@layer components {
  @layer buttons { /* ... */ }
  @layer cards { /* ... */ }
}

/* Add more rules to a nested layer later: */
@layer components.buttons {
  .btn-small { padding: 4px 8px; }
}

Nested layers are sorted within their parent. From the outside, all of components (including its sub-layers) still sits wherever components sits in the top-level order. Nesting is especially handy for importing a library that uses layers of its own: @import url("lib.css") layer(lib); keeps all of its internal layers neatly inside lib.

A practical layer structure

A common, effective setup looks like this:

CSS
@layer reset, base, layout, components, utilities;
  • reset: normalizes browser defaults (box-sizing, margins, font: inherit on form controls).
  • base: element styles for your site: body text, headings, links, tables.
  • layout: page structure: containers, grids, header and footer.
  • components: cards, buttons, menus, dialogs.
  • utilities: small single-purpose classes like .text-center or .visually-hidden that should beat components.
A tiny layered stylesheet

.card button has specificity (0, 1, 1), and .danger has only (0, 1, 0). Without layers the delete button would stay blue. Because utilities comes after components, the single class wins, which is exactly what you want from a utility. You will see a bigger version of this structure in Organizing CSS.

Debugging layers

Modern DevTools show the layer of each rule in the Styles panel, and Chromium-based browsers can display the complete layer order. When a rule loses unexpectedly, check its layer first, before you look at specificity. The most common mistakes are:

  • A layer used before the order statement, which creates it in the wrong position.
  • Code left unlayered by accident, which then beats everything.
  • Expecting a heavy selector in an early layer to beat a light selector in a later one.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. @layer base, components; A rule in base has specificity (1, 2, 0). A rule in components has (0, 1, 0). Both are normal and set the same property. Which wins?

    Layer order is compared before specificity. Specificity only settles conflicts inside the same layer.
  2. 2. How do unlayered normal styles compare to layered normal styles?

    For normal declarations, unlayered styles behave like a final layer after all named layers, so they win.
  3. 3. What determines the priority of layers?

    Layers are ordered by first appearance, which is why a @layer a, b, c; statement at the top is the usual way to fix the order.
  4. 4. Which line imports a stylesheet into a layer named vendor?

    @import accepts a layer() function. There is no supported HTML attribute for this yet.
  5. 5. With @layer reset, utilities;, both layers contain an important declaration for the same property. Which wins?

    For important declarations, layer order is reversed and earlier layers win.

Summary

  • @layer sorts CSS into named layers; between layers, layer order beats specificity.
  • Layers are ordered by first mention. Declare them all at the top: @layer reset, base, components, utilities;.
  • Later layers win for normal declarations, and unlayered styles beat all layers.
  • For !important declarations it reverses: earlier layers win, and layered beats unlayered.
  • @import url(...) layer(name) puts a stylesheet into a layer; layers can nest with dot names.
  • Put code you want to be weaker, such as resets and libraries, into early layers.

Next: Global Values: initial, inherit, unset, revert โ€” the keywords that work on every property.