W3C-style CSS variables syntax for Rework
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
test
.gitignore
.travis.yml
History.md
Readme.md
index.js
package.json

Readme.md

rework-vars Build Status

A Rework plugin to add support for the W3C-style CSS variables syntax.

N.B. This is not a polyfill. This plugin aims to provide a future-proof way of using a limited subset of the features provided by native CSS variables.

Installation

npm install rework-vars

Use

As a Rework plugin:

// dependencies
var fs = require('fs');
var rework = require('rework');
var vars = require('rework-vars');

// css to be processed
var css = fs.readFileSync('build/build.css', 'utf8').toString();

// process css using rework-vars
var options = {};
var out = rework(css).use(vars(options)).toString();

Options

map

Optionally, you may pass an object of variables - map - to the JavaScript function.

var map = {
  'app-bg-color': 'white'
}

var out = rework(css).use(vars({map: map})).toString();

preserve (default: false)

Setting preserve to true will preserve the variable definitions and references in the output, so that they can be used by supporting browsers.

var out = rework(css).use(vars({preserve: true})).toString();

Supported features

Variables can be declared as custom CSS properties on the :root element, prefixed with --:

:root {
  --my-color: red;
}

Variables are applied using the var() function, taking the name of a variable as the first argument:

:root {
  --my-color: red;
}

div {
  color: var(--my-color);
}

Fallback values are supported and are applied if a variable has not been declared:

:root {
  --my-color: red;
}

div {
  color: var(--other-color, green);
}

Fallbacks can be "complex". Anything after the first comma in the var() function will act as the fallback value – var(name, fallback). Nested variables are also supported:

:root {
  --my-color: red;
}

div {
  background: var(--my-other-color, linear-gradient(var(--my-color), rgba(255,0,0,0.5)));
}

What to expect

Variables can only be declared for, and scoped to the :root element. All other variable declarations are left untouched. Any known variables used as values are replaced.

:root {
  --color-one: red;
  --color-two: green;
}

:root,
div {
  --color-two: purple;
  color: var(--color-two);
}

div {
  --color-three: blue;
}

span {
  --color-four: yellow;
}

yields:

:root,
div {
  --color-two: purple;
  color: green;
}

div {
  --color-three: blue;
}

span {
  --color-four: yellow;
}

Variables are not dynamic; they are replaced with normal CSS values. The value of a defined variable is determined by the last declaration of that variable for :root.

:root {
  --brand-color: green;
}

.brand {
  color: var(--brand-color);
}

:root {
  --brand-color: red;
}

yields:

.brand {
  color: red;
}

Variables declared within @media or @supports are not currently supported and will also be ignored.

@media (min-width: 320px) {
  :root {
    --brand-color: red;
  }
}

yields:

@media (min-width: 320px) {
  :root {
    --brand-color: red;
  }
}

License

MIT