postcss-advanced-variables

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 $index from 1 to 5 by 2 {
  .col-$index {
    width: $(index)0%;
  }
}

/* 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-1 {
  width: 10%;
}

.col-3 {
  width: 30%;
}

.col-5 {
  width: 50%;
}

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 lets you specify your own global variables.

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

The variables option also accepts a function, which will be 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 lets you determine how unresolved variables 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
});

Changelog

2.0.0 (December 31, 2017)

• Completely rewritten
• Added: unresolved option to throw errors or warnings on unresolved variables
• Added: Support for the #{$var} syntax
• Added: Support for iterators in @each at-rules
• Added: Support for boolean @if at-rules (@each $item $index in $array)
• Added: Support for variable replacement in all at-rules
• Added: Support for neighboring variables $a$b
• Fixed: Number comparison in @if at-rules