postcss-variables

PostCSS Variables

Converts variables into CSS.

/* before (nesting requires postcss-nested) */

$dir: assets/icons;
$color: blue;

.block {
	background: url('$(dir)/foo.png');
	&__elem {
		$color: green;
		color: $color;
	}
	&__elem2 {
		color: $color;
	}
}

/* after */

.block {
	background: url('assets/icons/foo.png');
	&__elem {
		color: green;
	}
	&__elem2 {
		color: blue;
	}
}

Usage

Add PostCSS Variables to your build tool:

npm install postcss-variables --save-dev

Node

require('postcss-variables')({ /* options */ }).process(YOUR_CSS);

PostCSS

Add PostCSS to your build tool:

npm install postcss --save-dev

Load PostCSS Variables as a PostCSS plugin:

postcss([
	require('postcss-variables')({ /* options */ })
]);

Options

globals

Type: Object
Default: {}

Specifies your own global variables.

require('postcss-variables')({
	globals: {
		siteWidth: '960px',
		colors: {
			primary: '#fff',
			secondary: '#000'
		}
	}
});

/* before */

.hero {
	color: $colors.primary;
	max-width: $siteWidth;
}

/* after */

.hero {
	color: #fff;
	max-width: 960px;
}

Advanced

When creating your global variables, you may want to eliminate duplication by referencing an existing property to define your new variable. You can do this by referencing variables like you would in your stylesheet. Here is the basic idea:

let vars = {
	colors: {
		primary: '#fff'
	},
	heading: {
		color: '$colors.primary'
	}
 };

In certain circumstances, you may want to create a base variables file that you would want to be able to override. This would be a use-case if you were using this plugin inside of some kind of framework. If you are using functions to calculate global variables, you may want to delay the function execution until after you had a chance to override your variables. This can be done by using the defer method.

Here is a full example of how you might create a base variables file:

function darken(color, pct) {
	// Do something to calculate darker hex value
	return result
}

module.exports = {
	colors: {
		white: '#fff',
		gray: defer(darken, ['$colors.white', 35])
	}
 };

This is what a full example would look like in order to use these features:

/* variables.js */
const { defer } = require('postcss-variables/lib/helpers');
const register = require('postcss-variables/lib/register');

function darken(color, pct) {
	// Do something to calculate darker hex value
	return result
}

let vars = {
	colors: {
		primary: '#fff',
		gray: defer(darken, ['$colors.white', 35])
	},
	heading: {
		color: '$colors.primary'
	}
};

module.exports = register(vars);

Note: Please refer to Advanced Variables for more advanced features. This library is essentially a simplification and alteration of that plugin. Thank you to the author for making it available.