What is postcss-simple-vars?
The postcss-simple-vars package is a PostCSS plugin that allows you to use Sass-like variables in your CSS. It simplifies the process of managing and reusing values across your stylesheets, making your CSS more maintainable and easier to read.
What are postcss-simple-vars's main functionalities?
Variable Declaration
You can declare variables using the `$` symbol and then use these variables throughout your CSS. This makes it easy to manage and update values in one place.
/* CSS */
$primary-color: #3498db;
$padding: 10px;
.button {
background-color: $primary-color;
padding: $padding;
}
Variable Interpolation
You can perform operations on variables using interpolation. This allows for dynamic calculations and more flexible styling.
/* CSS */
$size: 10px;
.icon {
width: $(size * 2);
height: $(size * 2);
}
Default Variables
You can set default values for variables using the `!default` flag. This ensures that a variable is only assigned a value if it hasn't been defined previously.
/* CSS */
$primary-color: #3498db !default;
$primary-color: #e74c3c;
.button {
background-color: $primary-color;
}
Other packages similar to postcss-simple-vars
postcss-css-variables
The postcss-css-variables package allows you to use native CSS custom properties (variables) in a way that is compatible with older browsers. Unlike postcss-simple-vars, it focuses on providing a polyfill for native CSS variables rather than introducing a new syntax.
postcss-advanced-variables
The postcss-advanced-variables package extends the functionality of postcss-simple-vars by adding support for conditionals, loops, and more complex variable manipulations. It is more feature-rich but also more complex to use.
postcss-mixins
The postcss-mixins package allows you to create reusable chunks of CSS, similar to Sass mixins. While it doesn't focus solely on variables, it complements postcss-simple-vars by providing additional tools for code reuse and modularity.
PostCSS Simple Variables

PostCSS plugin for Sass-like variables.
You can use variables inside values, selectors and at-rule parameters.
$dir: top;
$blue: #056ef0;
$column: 200px;
.menu_link {
background: $blue;
width: $column;
}
.menu {
width: calc(4 * $column);
margin-$(dir): 10px;
}
.menu_link {
background: #056ef0;
width: 200px;
}
.menu {
width: calc(4 * 200px);
margin-top: 10px;
}
If you want be closer to W3C spec,
you should use postcss-custom-properties and postcss-at-rules-variables plugins.
Look at postcss-map for big complicated configs.
Interpolation
There is special syntax for using variables inside CSS words:
$prefix: my-company-widget
$prefix { }
$(prefix)_button { }
You can use variables in comments too (for example, to generate special
mdcss comments). Syntax for comment variables is different to separate
them from PreCSS code examples:
$width: 100px;
/* $width: <<$(width)>> */
compiles to:
Escaping
If you want to escape $
in the content
property, use Unicode escape syntax.
.foo::before {
content: "\0024x";
}
Usage
Step 1: Install plugin:
npm install --save-dev postcss postcss-simple-vars
Step 2: Check your project for existing PostCSS config: postcss.config.js
in the project root, "postcss"
section in package.json
or postcss
in bundle config.
If you do not use PostCSS, add it according to official docs
and set this plugin in settings.
Step 3: Add the plugin to plugins list:
module.exports = {
plugins: [
+ require('postcss-simple-vars'),
require('autoprefixer')
]
}
Options
Call plugin function to set options:
require('postcss-simple-vars')({ silent: true })
variables
Set default variables. It is useful to store colors or other constants
in a common file:
module.exports = {
blue: '#056ef0'
}
const colors = require('./config/colors')
const vars = require('postcss-simple-vars')
module.exports = {
plugins: [
require('postcss-simple-vars')({ variables: colors })
]
}
You can use a function return an object, if you want to update default
variables in webpack hot reload:
require('postcss-simple-vars')({
variables: function () {
return require('./config/colors');
}
})
onVariables
Callback invoked once all variables in css are known. The callback receives
an object representing the known variables, including those explicitly declared
by the variables
option.
require('postcss-simple-vars')({
onVariables (variables) {
console.log('CSS Variables');
console.log(JSON.stringify(variables, null, 2));
}
})
unknown
Callback on unknown variable name. It receives the node instance, variable name
and PostCSS Result object.
require('postcss-simple-vars')({
unknown (node, name, result) {
node.warn(result, 'Unknown variable ' + name);
}
})
])
silent
Leave unknown variables in CSS and do not throw an error. Default is false
.
only
Set value only for variables from this object.
Other variables will not be changed. It is useful for PostCSS plugin developers.
keep
Keep variables as is and not delete them. Default is false
.
Messages
This plugin passes result.messages
for each variable:
const result = await postcss([vars]).process('$one: 1; $two: 2')
console.log(result.messages)
will output:
[
{
plugin: 'postcss-simple-vars',
type: 'variable',
name: 'one'
value: '1'
},
{
plugin: 'postcss-simple-vars',
type: 'variable',
name: 'two'
value: '2'
}
]
You can access this in result.messages
and
in any plugin that included after postcss-simple-vars
.