PostCSS Custom Properties ![PostCSS Logo](https://postcss.github.io/postcss/logo.svg)
![Gitter Chat](https://img.shields.io/badge/chat-gitter-blue.svg)
PostCSS Custom Properties lets you use CSS Custom Properties in CSS, following
the CSS Custom Properties for Cascading Variables specification.
:root {
--color: red;
}
h1 {
color: var(--color);
}
:root {
--color: red;
}
div {
color: red;
color: var(--color);
}
Usage
Add PostCSS Custom Properties to your build tool:
npm install postcss-custom-properties --save-dev
Node
Use PostCSS Custom Properties to process your CSS:
import postCSSCustomProperties from 'postcss-custom-properties';
postCSSCustomProperties.process(YOUR_CSS);
PostCSS
Add PostCSS to your build tool:
npm install postcss --save-dev
Use PostCSS Custom Properties as a plugin:
import postcss from 'gulp-postcss';
import postCSSCustomProperties from 'postcss-custom-properties';
postcss([
postCSSCustomProperties()
]).process(YOUR_CSS);
Gulp
Add Gulp PostCSS to your build tool:
npm install gulp-postcss --save-dev
Use PostCSS Custom Properties in your Gulpfile:
import postcss from 'gulp-postcss';
import postCSSCustomProperties from 'postcss-custom-properties';
gulp.task('css', () => gulp.src('./src/*.css').pipe(
postcss([
postCSSCustomProperties()
])
).pipe(
gulp.dest('.')
));
Grunt
Add Grunt PostCSS to your build tool:
npm install grunt-postcss --save-dev
Use PostCSS Custom Properties in your Gruntfile:
import postCSSCustomProperties from 'postcss-custom-properties';
grunt.loadNpmTasks('grunt-postcss');
grunt.initConfig({
postcss: {
options: {
use: [
postCSSCustomProperties()
]
},
dist: {
src: '*.css'
}
}
});
Options
strict
The strict
option determines whether a var()
function should transform into
its specified fallback value. By default, the option is true
because this
plugin can not verify if the computed :root
value is valid or not.
:root {
--color: red;
}
div {
color: var(--color, blue);
}
:root {
--color: red;
}
div {
color: blue;
color: var(--color, blue);
}
preserve
The preserve
option determines how Custom Properties should be preserved. By
default, this option is truthy and preserves declarations containing var()
.
:root {
--color: red;
}
h1 {
color: var(--color);
}
:root {
--color: red;
}
h1 {
color: red;
color: var(--color);
}
The option may also be set to false
, where Custom Properties and declarations
containing var()
will be removed:
postCSSCustomProperties({
variables: {
preserve: false
}
})
:root {
--color: red;
}
h1 {
color: var(--color);
}
h1 {
color: red;
}
The option may also be set to "preserve-computed"
, where Custom Properties
will remain, but declarations containing var()
will be removed:
postCSSCustomProperties({
variables: {
preserve: 'preserve-computed'
}
})
:root {
--color: red;
}
h1 {
color: var(--color);
}
:root {
--color: red;
}
h1 {
color: red;
}
variables
The variables
option allows you to pass an object of variables into CSS, as if
they had been specified on :root
.
postCSSCustomProperties({
variables: {
color: 'red'
}
})
h1 {
color: var(--color);
}
h1 {
color: red;
color: var(--color);
}
Note that these definitions will override any that exist in the CSS, and that
the keys will be automatically prefixed (--
) to make it easier to share
variables in your codebase.
appendVariables
The appendVariables
option determines whether Custom Properties will be
appended to your CSS file. By default, this option is false
.
If enabled when preserve
is set to true
or "computed"
, this option allows
you to append your variables at the end of your CSS:
postCSSCustomProperties({
appendVariables: true,
variables: {
color: 'red'
}
})
h1 {
color: var(--color);
}
h1 {
color: red;
color: var(--color);
}
:root {
--color: red;
}
warnings
The warnings
option determines whether Custom Property related warnings should
be logged by the plugin or not. By default, warnings are set to false
and are
not logged.
If enabled, the plugin will enable all warnings:
postCSSCustomProperties({
warnings: true
})
h1 {
color: var(--color);
}
variable '--color' is undefined and used without a fallback
noValueNotifications
When warnings are enabled, the noValueNotifications
option determines whether
undefined variables will throw a warning or an error. By default, it is set to
warning
.
Notes
As written in the specification, usage of var()
is limited to property values.
Do not expect the plugin to transform var()
in media queries or in selectors.
The transformation of Custom Properties done by this plugin is not complete
and cannot be because dynamic cascading variables based on custom
properties relies on the DOM tree. Since we do not know the DOM in the context
of this plugin, we cannot produce safe output. This plugin currently aims to
provide a future-proof way of using a limited subset of the features
provided by native CSS custom properties.
There is a separate plugin, PostCSS CSS Variables, that attempts to guess the
context of Custom Properties without access to the DOM tree. This does not
reflecting the specifications,
so be sure you understand the risks before you decide to use it.
Contributing
Fork, work on a branch, install dependencies & run tests before submitting a PR.
$ git clone https://github.com/YOU/postcss-custom-properties.git
$ git checkout -b patch-1
$ npm install
$ npm test