# @csstools/postcss-cascade-layers > Use cascade layers in CSS Latest version **6.0.0** (published 2026-01-14) · MIT-0 license · 0 weekly downloads ## Install ```sh npm install @csstools/postcss-cascade-layers pnpm add @csstools/postcss-cascade-layers yarn add @csstools/postcss-cascade-layers bun add @csstools/postcss-cascade-layers ``` ## Health **Score 55/100 (C)** — status: stable. Positive: esm support; no vulnerabilities; high maintenance score. Warnings: low downloads; no types. ## Facts | | | |---|---| | Version | 6.0.0 | | Published | 2026-01-14 | | First published | 2022-05-12 | | Weekly downloads | 0 | | License | MIT-0 | | TypeScript types | none | | Module format | ESM | | Node | >=20.19.0 | | Dependencies | 2 | | Unpacked size | 18.9 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 1052 | | Maintainers | jonathantneal, alaguna, romainmenke | | Keywords | cascade, css, layers, postcss, postcss-plugin, selectors, specificity | ## Links - npm: https://www.npmjs.com/package/@csstools/postcss-cascade-layers - Repository: https://github.com/csstools/postcss-plugins - Homepage: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-cascade-layers#readme - Issues: https://github.com/csstools/postcss-plugins/issues - Funding: https://github.com/sponsors/csstools - npm.io page: https://npm.io/package/@csstools/postcss-cascade-layers ## Dependencies (2) - [postcss-selector-parser](https://npm.io/package/postcss-selector-parser.md) ^7.1.1 - [@csstools/selector-specificity](https://npm.io/package/@csstools/selector-specificity.md) ^6.0.0 ## Alternatives - [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads - [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads - [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads - [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads - [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads ## Recent versions - 6.0.0 (latest) — 2026-01-14 - 5.0.2 — 2025-06-26 - 5.0.1 — 2024-10-23 - 5.0.0 — 2024-08-03 - 4.0.6 — 2024-05-13 - 4.0.5 — 2024-05-11 - 4.0.4 — 2024-03-31 - 4.0.3 — 2024-02-19 - 4.0.2 — 2023-12-15 - 4.0.1 — 2023-10-31 - 4.0.0 — 2023-07-03 - 3.0.1 — 2023-01-28 - 3.0.0 — 2023-01-24 - 2.0.0 — 2022-11-14 - 1.1.1 — 2022-09-17 - … 8 more at https://npm.io/package/@csstools/postcss-cascade-layers/versions ## README # PostCSS Cascade Layers [PostCSS Logo][PostCSS] `npm install @csstools/postcss-cascade-layers --save-dev` [PostCSS Cascade Layers] lets you use `@layer` following the [Cascade Layers Specification]. For more information on layers, checkout [A Complete Guide to CSS Cascade Layers] by Miriam Suzanne. ```css target { color: purple; } @layer { target { color: green; } } /* becomes */ target:not(#\#) { color: purple; } target { color: green; } ``` ## How it works [PostCSS Cascade Layers] creates "layers" of specificity. It applies extra specificity on all your styles based on : - the most specific selector found - the order in which layers are defined ```css @layer A, B; @layer B { .a-less-specific-selector { /* styles */ } } @layer A { #something #very-specific { /* styles */ } } @layer C { .a-less-specific-selector { /* styles */ } } ``` most specific selector : - `#something #very-specific` - `[2, 0, 0]` - `2 + 1` -> `3` to ensure there is no overlap the order in which layers are defined : - `A` - `B` - `C` | layer | previous adjustment | specificity adjustment | selector | | ------ | ------ | ----------- | --- | | `A` | `0` | `0 + 0 = 0` | N/A | | `B` | `0` | `0 + 3 = 3` | `:not(#\#):not(#\#):not(#\#)` | | `C` | `3` | `3 + 3 = 6` | `:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#):not(#\#)` | This approach lets more important (later) layers always override less important (earlier) layers.
And layers have enough room internally so that each selector works and overrides as expected. More layers with more specificity will cause longer `:not(...)` selectors to be generated. > [!IMPORTANT] > [PostCSS Cascade Layers] assumes to process your complete CSS bundle.
If your build tool processes files individually or processes files in parallel the output will be incorrect.
Using [`@csstools/postcss-bundler`](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-bundler) and `@import` statements is one way to make sure your CSS is bundled before it is processed by this plugin. ## Usage Add [PostCSS Cascade Layers] to your project: ```bash npm install postcss @csstools/postcss-cascade-layers --save-dev ``` Use it as a [PostCSS] plugin: ```js const postcss = require('postcss'); const postcssCascadeLayers = require('@csstools/postcss-cascade-layers'); postcss([ postcssCascadeLayers(/* pluginOptions */) ]).process(YOUR_CSS /*, processOptions */); ``` ## Options ### onRevertLayerKeyword The `onRevertLayerKeyword` option enables warnings if `revert-layer` is used. Transforming `revert-layer` for older browsers is not possible in this plugin. Defaults to `warn` ```js postcssCascadeLayers({ onRevertLayerKeyword: 'warn' }) // 'warn' | false ``` ```css /* [postcss-cascade-layers]: handling "revert-layer" is unsupported by this plugin and will cause style differences between browser versions. */ @layer { .foo { color: revert-layer; } } ``` ### onConditionalRulesChangingLayerOrder The `onConditionalRulesChangingLayerOrder` option enables warnings if layers are declared in multiple different orders in conditional rules. Transforming these layers correctly for older browsers is not possible in this plugin. Defaults to `warn` ```js postcssCascadeLayers({ onConditionalRulesChangingLayerOrder: 'warn' }) // 'warn' | false ``` ```css /* [postcss-cascade-layers]: handling different layer orders in conditional rules is unsupported by this plugin and will cause style differences between browser versions. */ @media (min-width: 10px) { @layer B { .foo { color: red; } } } @layer A { .foo { color: pink; } } @layer B { .foo { color: red; } } ``` ### onImportLayerRule The `@import` at-rule can also be used with cascade layers, specifically to create a new layer like so: ```css @import 'theme.css' layer(utilities); ``` If your CSS uses `@import` with layers, you will also need the [postcss-import] plugin. This plugin alone will not handle the `@import` at-rule. This plugin will warn you when it detects that [postcss-import] did not transform`@import` at-rules. ```js postcssCascadeLayers({ onImportLayerRule: 'warn' }) // 'warn' | false ``` ### Contributors The contributors to this plugin were [Olu Niyi-Awosusi] and [Sana Javed] from [Oddbird] and Romain Menke. [cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test [css-url]: https://cssdb.org/#cascade-layers [discord]: https://discord.gg/bUadyRwkJS [npm-url]: https://www.npmjs.com/package/@csstools/postcss-cascade-layers [PostCSS]: https://github.com/postcss/postcss [PostCSS Cascade Layers]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-cascade-layers [Cascade Layers Specification]: https://www.w3.org/TR/css-cascade-5/#layering [A Complete Guide to CSS Cascade Layers]: https://css-tricks.com/css-cascade-layers/ [Olu Niyi-Awosusi]: https://github.com/oluoluoxenfree [Sana Javed]: https://github.com/sanajaved7 [Oddbird]: https://github.com/oddbird [postcss-import]: https://github.com/postcss/postcss-import --- _Source: https://npm.io/package/@csstools/postcss-cascade-layers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._