PostCSS Custom Properties

PostCSS Custom Properties lets you use Custom Properties in CSS, following the CSS Custom Properties specification.

:root {
    --color-blue-dark: rgb(0, 61, 184);
    --color-blue-light: rgb(0, 217, 255);
    --color-pink: rgb(255, 192, 211);
    --text-color: var(--color-pink);
}

.element {
    /* custom props */
    --border-color: var(--color-blue-light);

    /* props */
    border: 1px solid var(--border-color);
    color: var(--text-color);
}

.element--dark {
    --border-color: var(--color-blue-dark);
}

/* becomes */

:root {
    --color-blue-dark: rgb(0, 61, 184);
    --color-blue-light: rgb(0, 217, 255);
    --color-pink: rgb(255, 192, 211);
    --text-color: var(--color-pink);
}

.element {
    /* custom props */
    --border-color: var(--color-blue-light);

    /* props */
    border: 1px solid rgb(0, 217, 255);
    border: 1px solid var(--border-color);
    color: rgb(255, 192, 211);
    color: var(--text-color);
}

.element--dark {
    --border-color: var(--color-blue-dark);
}

Note: This plugin only processes variables that are defined in the :root or html selector.

Locally defined custom properties will be used as fallbacks only within the same rule, but not elsewhere.

Usage

Add PostCSS Custom Properties to your project:

npm install postcss postcss-custom-properties --save-dev

Use it as a PostCSS plugin:

const postcss = require('postcss');
const postcssCustomProperties = require('postcss-custom-properties');

postcss([
    postcssCustomProperties(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);

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

Options

preserve

The preserve option determines whether properties using custom properties should be preserved in their original form. By default these are preserved.

Custom property declarations are always preserved only var() functions can be omitted.

postcssCustomProperties({ preserve: false })

:root {
    --color-blue-dark: rgb(0, 61, 184);
    --color-blue-light: rgb(0, 217, 255);
    --color-pink: rgb(255, 192, 211);
    --text-color: var(--color-pink);
}

.element {
    /* custom props */
    --border-color: var(--color-blue-light);

    /* props */
    border: 1px solid var(--border-color);
    color: var(--text-color);
}

.element--dark {
    --border-color: var(--color-blue-dark);
}

/* becomes */

:root {
    --color-blue-dark: rgb(0, 61, 184);
    --color-blue-light: rgb(0, 217, 255);
    --color-pink: rgb(255, 192, 211);
    --text-color: var(--color-pink);
}

.element {
    /* custom props */
    --border-color: var(--color-blue-light);

    /* props */
    border: 1px solid var(--border-color);
    color: rgb(255, 192, 211);
}

.element--dark {
    --border-color: var(--color-blue-dark);
}