@layer - CSS At-rule

Description of the @layer at-rule.

The @layer at-rule defines the cascade layers, and above all, organizes their priorities. A tutorial on cascading layers is presented a little further down this page. Basically, cascade layers allow you to change the usual CSS priority rules.

To review the usual CSS priority rules, refer to the page Priorities.

Syntaxes of the @layer at-rule.

• @layer layer-1, layer-2, ... layer-n;

  This writing, usually placed at the beginning of the styles-sheet, defines a series of cascade layers. You just need to list the names of these layers, separating them with commas. The chosen names must start with a letter and can include letters, numbers, hyphens, and underscores. But it's better to stick to CSS best practices and go for a kebab-case style: layer-1 instead of layer_1.

  The priority of these layers among themselves is also defined by the order in which they are listed: in our example, layer-1 is the least prioritized, and layer-n is the one with the highest priority.

  Once they are set, these priorities can't change, even if a second @layer directive comes up later. So, in the example below, layer-1 remains the layer with the lowest priority:

  @layer layer-1, layer-2, layer-3; @layer layer-3, layer-2, layer-1;

  But it's possible to define new layers. In this case, since they're declared afterward, these new layers will have a higher priority. In this second example, a layer-4 layer is created with a priority higher than all the other layers that already exist. The priorities of layers 1 to 3 don't change.

  @layer layer-1, layer-2, layer-3; @layer layer-4, layer-3, layer-2;

  All CSS syntaxes can be inserted into a cascade layer, except:

  • The @charset at-rule. Indeed, this at-rule must be unique and appear at the very beginning of the style sheet.
  • The @namespace at-rule that defines a namespace. This at-rule is mainly used when styles are applied to an XML document.
  • The @import at-rule. See the syntax further down for importing styles into a cascade layer.
• @layer layer-1 { <selecteur> { <propriété>: <valeur>; <propriété>: <valeur>; } }

  In this second syntax, @layer is used to link CSS properties to a cascade layer. The priority of these properties will be changed by the priority of the cascade layer.

  If the specified name for the layer already exists, the priority of this layer will not be changed. If the name hasn't been set yet, a new layer is created with that name and with the highest priority.

• @import url("styles.css") layer(layer-1);

  A complementary syntax, which doesn't use the @layer at-rule but the @import at-rule. It lets you load an external styles-sheet directly into the specified cascade layer.

  Check out the @import directive for more details.

  For your information, the HTML link tag also allows you to specify the name of the cascade layer where the styles should be inserted:

  <link rel="stylesheet" href="styles.css" layer="layer-1">

Tutorial on cascade layers.

Reminder: priorities in CSS.

CSS applies some very specific rules to resolve conflicts between multiple rules whose selectors point to the same elements. Let's take the example below, which shows a snippet of HTML code and some styles. All three CSS rules apply to the paragraph in the example, but they use different selectors.

The classic priority rules state that the paragraph should be displayed in red, and so the second and third rules should be ignored. Indeed, the priority of each rule depends on the type of selector:

For more detailed explanations, check out the page on Priorities in CSS.

How is this way of working a problem?

Let's be clear: this priority mechanism is almost always very effective and rarely causes problems.

However, components are often integrated into a website, and some of them come with a styles-sheet. To make the visual integration look right, the developer often wants to override the styles that come with the component. If these use ID selectors, they already have high priority and will be hard to override..

Let's take an example. Below, the component comes with a styles-sheet that sets the main element of the component to blue. This element is targeted by its ID component. It is therefore difficult to change its color in the site's styles-sheet. You have to find a selector with higher priority, which is done in the example by preceding the ID with div.
Selector #component: specificity of 100.
Selector div#component: specificity of 101.

It works but it's not very elegant; Plus, it assumes you know that the main element of the component is a div.

The !important option.

Another way to override an existing rule that has a high-priority selector is to add the !important option at the end of the new rule. Rules with this option become more important than all others.

However, one can guess that this solution lacks subtlety: it destroys the usual priority mechanism which is, after all, in most cases, very practical and necessary. And if we have to override a rule that already has the !important option, we’ll need to put that option on the new rule. We often notice that after breaking the priority mechanism once, we end up having to put !important everywhere.

Cascade layers.

Cascade layers allow for much finer priority management: it is possible to define as many layers as needed and to set their priority relative to each other. The CSS rules associated with each layer take the priority of their layer. The best way is to take an example.

We define 3 layers in increasing order of priority base with the lowest priority, special with the highest priority @layer base, theme, special; Rules are then associated with the layers @layer base { .classe {color: black;} /* lower priority */ } @layer special { .classe {color: red;} /* high priority */ }

Notes: within the same layer, priorities are managed by the usual mechanism: the specificity of the selector defines the priority.
CSS rules that are not associated with a layer remain higher priority than those that are associated with a layer.

Let's rewrite the styles for our component using cascade layers:

Nested cascade layers.

Directives @layer can be nested within each other. This allows for defining multiple layers of cascading.

@layer group-1 { @layer layer-1 { ... } @layer layer-2 { ... } }

But it's often simpler to use dot notation to describe the nesting of layers:

@layer group-1.layer-1, group-1.layer-2; @layer group-1.layer-1 { ... } @layer group-1.layer-2 { ... }

The value revert-layer.

This new value, introduced in level 5 of the 'CSS Cascading and Inheritance' standardization module, cancels out changes made to a property's value in the same cascade layer. Changes made in another cascade layer are preserved.

Refer to page revert-layer for additional details.

Browsers compatibility with the @layer at-rule.

Cascade layers are now well handled by browsers. So it's really interesting to use them, especially if you're writing components that use their own styles.

1

Cascade
layers

2

@layer
at-rule

Estimated overall support.

96%

96%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

UC Browser pour Androïd

Opéra Mobile

QQ Browser

Baidu Browser

Samsung Internet

Chrome

Edge

Opéra

Safari sur IOS

Safari

Firefox

Androïd Brower

Chrome pour Androïd

Firefox pour Androïd

KaiOS Browser

Opéra mini

See Caniuse.com for more compatibility information.

Caniuse

Caniuse

Evolution of the @layer at-rule.

• CSS Cascading and Inheritance Level 5

  This specification module introduces the concept of style layer, the @layer directive, and the revert-layer value.

  Regarding @layer Introduction of cascade layers and the @layer at-rule.
  

  January 19, 2021

  Working Draft.

  

  January 13, 2022

  Candidate Recommendation.

  

  

Valso hear about, regarding the organization of styles-sheets.

The specification "CSS Cascading and Inheritance" gathers the tools available to organize styles in complex cases (many style sheets, large inheritance cascades, etc.).

Properties:

At-rules:

@import

Importing a stylesheet, with the possibility of choosing a cascade layer.

@layer

Defines cascade layers to help manage priorities between CSS rules.

⚠

@scope

Limit the scope of the instructions encompassed by this directive.

Values: