Ninja Power Manifesto

    @csstools/postcss-progressive-custom-properties
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.0 • Public • Published

    PostCSS Progressive Custom Properties PostCSS

    NPM Version Build Status Discord

    PostCSS Progressive Custom Properties is a utility plugin to correctly declare Custom Property fallbacks and enhancements.

    ⚠️ 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. This makes it tricky to provide fallback values for older browsers.

    The solution is to wrap Custom Property declarations in an @supports rule.

    :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 <white space> are ignored.

    .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:

    npm install @csstools/postcss-progressive-custom-properties --save-dev

    Use PostCSS Progressive Custom Properties as a PostCSS plugin:

    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.

    PostCSS Progressive Custom Properties runs in all Node environments, with special instructions for:

    Node PostCSS CLI Webpack Gulp Grunt

    Install

    npm i @csstools/postcss-progressive-custom-properties

    DownloadsWeekly Downloads

    3,806,902

    Version

    2.1.0

    License

    CC0-1.0

    Unpacked Size

    45 kB

    Total Files

    11

    Last publish

    Collaborators

    • alaguna
    • jonathantneal