PostCSS Advanced Variables

PostCSS Advanced Variables lets you use Sass-like variables, conditionals, and iterators in CSS.

$dir: assets/icons;

@each $icon in (foo, bar, baz) {
  .icon-$icon {
    background: url('$dir/$icon.png');
  }
}

@for $count from 1 to 5 by 2 {
  @if $count > 2 {
    .col-$count {
      width: #{$count}0%;
    }
  }
}

@import "path/to/some-file";

/* after */

.icon-foo {
  background: url('assets/icons/foo.png');
}

.icon-bar {
  background: url('assets/icons/bar.png');
}

.icon-baz {
  background: url('assets/icons/baz.png');
}

.col-3 {
  width: 30%;
}

.col-5 {
  width: 50%;
}

// the contents of "path/to/_some-file.scss"

Usage

Add PostCSS Advanced Variables to your build tool:

npm install postcss-advanced-variables --save-dev

Node

Use PostCSS Advanced Variables to process your CSS:

require('postcss-advanced-variables').process(YOUR_CSS);

PostCSS

Add PostCSS to your build tool:

npm install postcss --save-dev

Use PostCSS Advanced Variables as a plugin:

postcss([
  require('postcss-advanced-variables')(/* options */)
]).process(YOUR_CSS);

Gulp

Add Gulp PostCSS to your build tool:

npm install gulp-postcss --save-dev

Use PostCSS Advanced Variables in your Gulpfile:

var postcss = require('gulp-postcss');

gulp.task('css', function () {
  return gulp.src('./src/*.css').pipe(
    postcss([
      require('postcss-advanced-variables')(/* options */)
    ])
  ).pipe(
    gulp.dest('.')
  );
});

Grunt

Add Grunt PostCSS to your build tool:

npm install grunt-postcss --save-dev

Use PostCSS Advanced Variables in your Gruntfile:

grunt.loadNpmTasks('grunt-postcss');

grunt.initConfig({
  postcss: {
    options: {
      use: [
        require('postcss-advanced-variables')(/* options */)
      ]
    },
    dist: {
      src: '*.css'
    }
  }
});

Options

variables

The variables option defines global variables used when they cannot be resolved automatically.

require('postcss-advanced-variables')({
  variables: {
    'site-width': '960px'
  }
});

The variables option also accepts a function, which is given 2 arguments; the name of the unresolved variable, and the PostCSS node that used it.

require('postcss-advanced-variables')({
  variables(name, node) {
    if (name === 'site-width') {
      return '960px';
    }

    return undefined;
  }
});

.hero {
  max-width: $site-width;
}

/* after */

.hero {
  max-width: 960px;
}

unresolved

The unresolved option defines how unresolved variables, mixins, and imports should be handled. The available options are throw, warn, and ignore. The default option is to throw.

require('postcss-advanced-variables')({
  unresolved: 'ignore' // ignore unresolved variables
});

disable

The disable option defines which features should be disabled in PostCSS Advanced Variables.

The disable option can be a string or an array, and the features that can be disabled are @content, @each, @else, @if, @include, @import, @for, and @mixin.

require('postcss-advanced-variables')({
  disable: '@mixin, @include, @content' // ignore @mixin, @include, and @content at-rules
});

Import Options

importPaths

The importPaths option defines a path or multiple paths used to lookup files when they cannot be found automatically.

The importPaths option can be a string or an array.

By default, imports are resolved using the Sass Import Resolve Specification.

require('postcss-advanced-variables')({
  importPaths: ['path/to/files', 'another/path/to/files']
});

importResolve

The importResolve option defines the file resolver used by imports. It is a function given 3 arguments; the url id, the current working directory, and the options processed by PostCSS Advanced Variables.

The importResolve function should return a Promise with an object containing the full path (file) and the contents of the file (contents).

const resolve = require('custom-resolver');

require('postcss-advanced-variables')({
  // a resolver may work many ways, and this is just an example
  importResolve: (id, cwd, opts) => resolve({ id, cwd });
});

importRoot

The importRoot option defines the root directory used by imports when the current directory cannot be detected. Its default value is process.cwd().

require('postcss-advanced-variables')({
  importRoot: 'path/to/root'
});

importCache

The importCache option defines a cache made available to the options object that may be used by the file resolver.

const sharedCache = {};

require('postcss-advanced-variables')({
  importCache: sharedCache
});