CSS @layer Import Syntax for External Stylesheets

This article explains how to use the CSS @layer import syntax to load entire external stylesheets directly into designated cascade layers. By integrating the layer keyword or function into standard @import rules, developers can manage the cascade priority of third-party frameworks, design systems, and modular styles without modifying the source code of the external files.

Basic Syntax for Named Layers

To import an external stylesheet into a specific named layer, add the layer() function directly after the file path or url() specification in your @import rule.

/* Using the url() notation */
@import url("framework.css") layer(framework);

/* Using direct string notation */
@import "components.css" layer(components);

In this syntax, all CSS rules inside framework.css are assigned to the framework layer, and all rules in components.css are assigned to the components layer.

Importing into Anonymous Layers

If you want to assign an external stylesheet to its own isolated layer without explicitly naming it, omit the parentheses and use the layer keyword by itself.

@import url("normalize.css") layer;

This creates an anonymous layer for normalize.css. Anonymous layers cannot be referenced elsewhere in your styles to adjust their order, meaning their precedence is determined entirely by where this @import statement appears relative to other layer declarations.

Targeting Nested Layers

You can assign imported stylesheets directly into nested sub-layers using standard dot notation inside the layer() function.

@import url("buttons.css") layer(components.buttons);

This imports the styles into the buttons layer nested inside the parent components layer, preserving fine-grained cascade control across multi-tier styling architectures.

Syntax Order with Media and Supports Queries

When combining the layer() function with media queries or @supports feature conditions, the layer declaration must always precede them. The required order is the URL, followed by the layer, followed by any feature or media queries.

/* Layer with a media query */
@import url("dark-theme.css") layer(themes) (prefers-color-scheme: dark);

/* Layer with supports condition and media query */
@import url("grid-layout.css") layer(layouts) supports(display: grid) screen and (min-width: 768px);

Placing the layer() declaration after a media query or supports query will result in a syntax error, causing the browser to ignore the import statement.

Cascade Behavior of Imported Layers

The priority of imported layers follows standard CSS cascade layer rules: layers declared first have the lowest priority, while layers declared later have higher priority. To ensure complete control over precedence, define your intended layer order at the very top of your root stylesheet before executing your @import statements:

/* Explicitly establish layer order first */
@layer reset, framework, components, utilities;

/* Import external files into the defined layers */
@import url("reset.css") layer(reset);
@import url("bootstrap.css") layer(framework);
@import url("custom-components.css") layer(components);

Regardless of the selector specificity inside bootstrap.css, styles defined within custom-components.css will consistently override them because the components layer is ordered after the framework layer.