# @csstools/postcss-progressive-custom-properties > Correctly declare progressive enhancements for CSS Custom Properties. Latest version **5.1.3** (published 2026-09-06) · MIT-0 license · 0 weekly downloads ## Install ```sh npm install @csstools/postcss-progressive-custom-properties pnpm add @csstools/postcss-progressive-custom-properties yarn add @csstools/postcss-progressive-custom-properties bun add @csstools/postcss-progressive-custom-properties ``` ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types. ## Facts | | | |---|---| | Version | 5.1.3 | | Published | 2026-09-06 | | First published | 2022-02-06 | | Weekly downloads | 0 | | License | MIT-0 | | TypeScript types | none | | Module format | ESM | | Node | >=20.19.0 | | Dependencies | 1 | | Unpacked size | 52.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 1052 | | Author | Jonathan Neal | | Maintainers | jonathantneal, alaguna, romainmenke | | Keywords | css, custom, declarations, postcss, postcss-plugin, progressive, properties, utility, variables, vars | ## Links - npm: https://www.npmjs.com/package/@csstools/postcss-progressive-custom-properties - Repository: https://github.com/csstools/postcss-plugins - Homepage: https://github.com/csstools/postcss-plugins#readme - Issues: https://github.com/csstools/postcss-plugins/issues - Funding: https://github.com/sponsors/csstools - npm.io page: https://npm.io/package/@csstools/postcss-progressive-custom-properties ## Dependencies (1) - [postcss-value-parser](https://npm.io/package/postcss-value-parser.md) ^4.2.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 - 5.1.3 (latest) — 2026-09-06 - 5.1.2 — 2026-08-15 - 5.1.1 — 2026-06-28 - 5.1.0 — 2026-05-13 - 5.0.0 — 2026-01-14 - 4.2.1 — 2025-09-21 - 4.2.0 — 2025-08-22 - 4.1.0 — 2025-05-27 - 4.0.1 — 2025-04-19 - 4.0.0 — 2024-08-03 - 3.3.0 — 2024-07-07 - 3.2.0 — 2024-03-31 - 3.1.1 — 2024-03-13 - 3.1.0 — 2024-02-19 - 3.0.3 — 2023-12-15 - … 13 more at https://npm.io/package/@csstools/postcss-progressive-custom-properties/versions ## README # PostCSS Progressive Custom Properties [PostCSS][postcss] [![NPM Version][npm-img]][npm-url] [![Build Status][cli-img]][cli-url] [Discord][discord] [PostCSS Progressive Custom Properties] is a utility plugin to correctly declare Custom Property fallbacks and enhancements. > [!WARNING] > It is not intended to be used directly by stylesheet authors. > Meant to be included in other PostCSS plugins that provide CSS value transforms as fallbacks. [Custom Properties are not discarded like regular declarations when invalid.](https://www.w3.org/TR/css-variables-1/#invalid-variables) This makes it tricky to provide fallback values for older browsers. The solution is to wrap Custom Property declarations in an `@supports` rule. ```css :root { /* fallback */ --a-color: red; /* progressive enhancement */ --a-color: oklch(40% 0.234 0.39 / var(--opacity-50)); } /* becomes */ :root { --a-color: red; } @supports (color: oklch(0% 0 0)) { :root { --a-color: oklch(40% 0.234 0.39 / var(--opacity-50)); } } ``` ## Ignored values `initial` and `` are ignored. ```css .initial { --prop-1: red; --prop-1: initial; } .white-space { --prop-1: red; --prop-1:; --prop-2: red; --prop-2: ; --prop-3: red; --prop-3: ; } /* remains */ .initial { --prop-1: red; --prop-1: initial; } .white-space { --prop-1: red; --prop-1:; --prop-2: red; --prop-2: ; --prop-3: red; --prop-3: ; } ``` ## Usage Add [PostCSS Progressive Custom Properties] to your project: ```bash npm install @csstools/postcss-progressive-custom-properties --save-dev ``` Use [PostCSS Progressive Custom Properties] as a [PostCSS] plugin: ```js const postcss = require('postcss'); const postcssCustomProperties = require('@csstools/postcss-progressive-custom-properties'); postcss([ postcssProgressiveCustomProperties() ]).process(YOUR_CSS /*, processOptions */); ``` ## @supports This plugin wraps Custom Property override declarations in an `@supports` rule. With PostCSS 8 this trigger declaration visitors to run again. Make sure your plugin detects and ignores values inside relevant `@supports` rules. ## Reading list - https://moderncss.dev/how-custom-property-values-are-computed/ [PostCSS Progressive Custom Properties] runs in all Node environments, with special instructions for: | [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) | | --- | --- | --- | --- | --- | [cli-img]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml/badge.svg [cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test [discord]: https://discord.gg/bUadyRwkJS [npm-img]: https://img.shields.io/npm/v/@csstools/postcss-progressive-custom-properties.svg [npm-url]: https://www.npmjs.com/package/@csstools/postcss-progressive-custom-properties [PostCSS]: https://github.com/postcss/postcss [PostCSS Progressive Custom Properties]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties --- _Source: https://npm.io/package/@csstools/postcss-progressive-custom-properties · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._