@layer

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The @layer CSS at-rule declares a cascade layer, rules within a cascade layer cascade together, giving more control over the cascade to web developers.

@layer utilities {
  /* creates a named layer called utilities. */
}

Syntax

The @layer at-rule is used to create a cascade layer in one of three ways. The first is as in the example above, creating a block at-rule with the CSS rules for that layer inside.

@layer utilities {
  .padding-sm {
    padding: .5rem;
  }

  .padding-lg {
    padding: .8rem;
  }
}

A cascade layer can be created with @import, in this case the rules would be in the imported stylesheet:

@import(utilities.css) layer(utilities);

You can also create a named cascade layer without assigning any styles. This can be a single name:

@layer utilities

Or, multiple layers can be defined at once. For example:

@layer theme, layout, utilities

This is useful because the initial order in which layers are declared indicates which layer has precedence. As with declarations, the last layer to be listed will win if declarations are found in multiple layers. Therefore, with the preceding example, if a competing rule was found in theme and utilities the one in utilities would win and be applied.

The rule in utilities would be applied even if it has lower specificity than the rule in theme. This is because once layer order has been established, specificity and order of appearance are ignored. This enables the creation of simpler CSS selectors, as you do not have to ensure that a selector will have high enough specificity to override competing rules, all you need to ensure is that it appears in a later layer.

Note: Having declared your layer names, thus setting their order, you can add CSS rules to the layer by redeclaring the name. The styles are then appended to the layer and the layer order will not be changed.

Any styles not in a layer are gathered together and placed into an anonymous layer that comes first in the order of layers, this means that anything in a layer will override things not in a layer.

Nesting layers

Layers may be nested. For example:

@layer framework {
  @layer layout {

  }
}

To append rules to the layout layer inside framework join the two names with a ..

@layer framework.layout {
  p {
    margin-block: 1rem;
  }
}

Anonymous layers

If a layer is created with no name, for example:

@layer {
  p {
    margin-block: 1rem;
  }
}

Then an anonymous, unnamed, layer is created. This functions in the same way as named layers, however rules cannot be assigned to it later.

Formal syntax

No syntax available: No value found in the database.

Examples

Simple example

In the following example, two CSS rules are created. One for the <p> element, which is inside a layer named type. In addition a rule is created outside of any layer for .box p.

Without layers, the selector box p would have the highest specificity and therefore the text Hello, world! will display in green. With layers, specificity and order outside of layers is ignored. As the type layer comes after the anonymous layer created to hold non-layer content, the text will be purple.

HTML

<div class="box">
  <p>Hello, world!</p>
</div>

CSS

@layer type {
  p {
    color: rebeccapurple;
  }
}

.box p {
  font-weight: bold;
  color: green;
}

Result

Assigning rules to existing layers

In the following example, two layers are created with no rules applied, then CSS rules are applied to the two layers. The base layer defines a color, border, font-size, and padding. The special layer defines a different color. As special comes last when the layers were defined, the color it provides is used and the text is displayed using rebeccapurple. All of the other rules from base still apply.

HTML

<div class="item">I am displayed in <code>color: rebeccapurple</code>
because the <code>special</code> layer comes after the <code>base</code> layer.
My green border, font-size, and padding come from the <code>base</code> layer.</div>

CSS

@layer base, special;

@layer special {
  .item {
    color: rebeccapurple;
  }
}

@layer base {
  .item {
    color: green;
    border: 5px solid green;
    font-size: 1.5em;
    padding: .5em;
  }
}

Result

Specifications

No specification found

No specification data found for css.at-rules.layer.
Check for problems with this page or contribute a missing spec_url to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

Browser compatibility

No compatibility data found for css.at-rules.layer.
Check for problems with this page or contribute missing data to mdn/browser-compat-data.

See also