postcss-custom-properties

PostCSS Custom Properties

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);
}

/* becomes */

: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);
}

/* becomes */

: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);
}

/* becomes */

: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);
}

/* becomes */

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);
}

/* becomes */

: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);
}

/* becomes */

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);
}

/* becomes */

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

---

Changelog

License