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";
.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%;
}
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')()
]).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')()
])
).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')()
]
},
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;
}
.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'
});
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'
});
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')({
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
});