PostCSS API

postcss function
Processor class
LazyResult class
Result class
Warning class
CssSyntaxError class
Vendor module
List module
Input class
Nodes common methods
Containers common methods
Root node
AtRule node
Rule node
Declaration node
Comment node

`postcss` function

The postcss function is the main entry point for PostCSS.

var postcss = require('postcss');

`postcss(plugins)`

Returns a new Processor instance that will apply plugins as CSS processors.

postcss([autoprefixer, cssnext, cssgrace]).process(css).css;

Arguments:

plugins (array): PostCSS plugins list to set them to new processor.

You can also set plugins with the Processor#use method. See its description below for details about plugin formats.

`postcss.parse(css, opts)`

Parses source css and returns a new Root node, which contains the source CSS nodes.

// Simple CSS concatenation with source map support
var root1 = postcss.parse(css1, { from: file1 });
var root2 = postcss.parse(css2, { from: file2 });
root1.append(root2).toResult().css;

Arguments:

css (string|#toString): String with input CSS or any object with toString() method, like file stream.
opts (object) optional: options:
- from: the path to the source CSS file. You should always set from, because it is used in map generation and in syntax error messages.
- safe: enable Safe Mode, in which PostCSS will try to fix CSS syntax errors.
- map: an object of source map options. Only map.prev is used in parse.

`postcss.plugin(name, initializer)`

Creates PostCSS plugin with standard API.

var remove = postcss.plugin('postcss-remove', function (opts) {
    var filter = opts.prop || 'z-index';
    return function (css, processor) {
        css.eachDecl(filter, function (decl) {
            decl.removeSelf();
        });
    };
});

postcss().use(remove)                    // with default options
postcss().use(remove({ prop: 'color' })) // with options

Arguments:

name (string): PostCSS plugin name. Same as in name property in package.json. It will be saved in plugin.postcssPlugin property.
initializer (function): will receive plugin options and should return functions to modify nodes in input CSS.

Also wrap will save plugin name and plugin PostCSS version:

var processor = postcss([replace]);
processor.plugins[0].postcssPlugin  //=> 'postcss-replace'
processor.plugins[0].postcssVersion //=> '4.1.0'

Plugin function receive 2 arguments: Root node and Result instance. Then it should mutate the passed Root node, or you can create new Root node and put it to result.root property.

postcss.plugin('postcss-cleaner', function () {
    return function (css, result) {
        result.root = postcss.root();
    };
});

Asynchronous plugin should return Promise instance.

postcss.plugin('postcss-import', function () {
    return function (css, result) {
        return new Promise(function (resolve, reject) {
            fs.readFile('base.css', function (base) {
                css.prepend(base);
                resolve();
            })
        });
    };
});

You can add warnings by Result#warn() method.

postcss.plugin('postcss-caniuse-test', function () {
    return function (css, result) {
        css.eachDecl(function (decl) {
            if ( !caniuse.support(decl.prop) ) {
                result.warn(
                    'Some of browsers does not support ' + decl.prop,
                    { node: decl });
            }
        });
    };
});

You can send some data to next plugins by Result#messages array.

`postcss.root(props)`

Creates a new Root node.

postcss.root({ after: '\n' }).toString() //=> "\n"

Arguments:

props (object) optional: properties for new node.

`postcss.atRule(props)`

Creates a new AtRule node.

postcss.atRule({ name: 'charset' }).toString() //=> "@charset"

Arguments:

props (object) optional: properties for new node.

`postcss.rule(props)`

Creates a new Rule node.

postcss.rule({ selector: 'a' }).toString() //=> "a {\n}"

Arguments:

props (object) optional: properties for new node.

`postcss.decl(props)`

Creates a new Declaration node.

postcss.decl({ prop: 'color', value: 'black' }).toString() //=> "color: black"

Arguments:

props (object) optional: properties for new node.

`postcss.comment(props)`

Creates a new Comment node.

postcss.comment({ text: 'test' }).toString() //=> "/* test */"

Arguments:

props (object) optional: properties for new node.

`postcss.vendor`

Contains Vendor module module.

postcss.vendor.unprefixed('-moz-tab') //=> ['tab']

`postcss.list`

Contains List module module.

postcss.list.space('5px calc(10% + 5px)') //=> ['5px', 'calc(10% + 5px)']

`Processor` class

A Processor instance contains plugins to process CSS. You can create one Processor instance, initialize its plugins, and then use that instance on many CSS files.

var processor = postcss([autoprefixer, cssnext, cssgrace]);
processor.process(css1).css;
processor.process(css2).css;

`processor.use(plugin)`

Adds a plugin to be used as a CSS processor.

var processor = postcss();
processor.use(autoprefixer).use(cssnext).use(cssgrace);

Arguments:

plugin (function|#postcss|Processor): PostCSS plugin. I can be in three formats:
- A plugin created by postcss.plugin() method.
- A function. PostCSS will pass the function a Root node as the first argument and current Result instance as second.
- An object with a postcss method. PostCSS will use that method as described in #2.
- Another Processor instance. PostCSS will copy plugins from that instance to this one.

Plugins can also be added by passing them as arguments when creating a postcss instance (see postcss(plugins)).

Asynchronous plugin should return Promise instance.

`processor.process(css, opts)`

Parses source CSS and returns LazyResult instance. Because some plugins can be asynchronous it doesn’t make any transformations. Transformations will be apply in LazyResult’s methods.

processor.process(css, { from: 'a.css', to: 'a.out.css' }).then(function (result) {
    console.log(result.css);
});

Arguments:

css (string|#toString|Result): String with input CSS or any object with toString() method, like file stream. Also you can send Result instance and processor will take already parser [Root] from it.
ops (object) optional: options:
- from: the path of the CSS source file. You should always set from, because it is used in source map generation and syntax error messages.
- to: the path where you’ll put the output CSS file. You should always set to to generate correct source maps.
- safe: enable Safe Mode, in which PostCSS will try to fix CSS syntax errors.
- map: an object of source map options.

`processor.plugins`

Contains plugins added to this processor.

var processor = postcss([cssnext, cssgrace]);
processor.plugins.length //=> 2

`processor.version`

Contains current version of PostCSS.

postcss().version //=> '4.0.5'

`LazyResult` class

Promise proxy for result of PostCSS transformations.

A LazyResult instance is returned by Processor#process(css, opts).

var lazy = postcss([cssnext]).process(css);

`lazy.then(onFulfilled, onRejected)`

Processes input CSS through synchronous and asynchronous plugins and call onFulfilled with Result instance. If some plugin will throw a error, onRejected callback will be executed.

postcss([cssnext]).process(css).then(function(result) {
    console.log(result.css);
});

This method is a standard Promise method.

`lazy.catch(onRejected)`

Processes input CSS through synchronous and asynchronous plugins and call onRejected on errors from any plugin.

postcss([cssnext]).process(css).then(function(result) {
    console.log(result.css);
}).catch(function (error) {
    console.error(error);
});

This method is a standard Promise method.

`lazy.toString()`

Alias for LazyResult#css property.

`lazy.css`

Processes input CSS through synchronous plugins, convert Root to CSS string and returns Result#css.

processor.process(css).css;

This property will work only with synchronous plugins. If processor contains any asynchronous plugin it will throw a error. You should use LazyResult#then() instead.

postcss([cssnext]).then(function (result) {
    console.log(result.css);
});

`lazy.map`

Processes input CSS through synchronous plugins and returns Result#map.

if ( result.map ) {
    fs.writeFileSync(result.opts.to + '.map', result.map.toString());
}

This property will work only with synchronous plugins. If processor contains any asynchronous plugin it will throw a error. You should use LazyResult#then() instead.

postcss([cssnext]).then(function (result) {
    if ( result.map ) {
        fs.writeFileSync(result.opts.to + '.map', result.map.toString());
    }
});

`lazy.root`

Processes input CSS through synchronous plugins and returns Result#root.

This property will work only with synchronous plugins. If processor contains any asynchronous plugin it will throw a error. You should use LazyResult#then() instead.

postcss([cssnext]).then(function (result) {
    console.log(result.root);
});

`lazy.warnings()`

Processes input CSS through synchronous plugins and call [Result#warnings()].

postcss([cssnext]).warnings().forEach(function (message) {
    console.warn(message.text);
});

This property will work only with synchronous plugins. If processor contains any asynchronous plugin it will throw a error. You should use LazyResult#then() instead.

postcss([cssnext]).then(function (result) {
    result.warnings().forEach(function (message) {
        console.warn(message.text);
    });
});

`lazy.messages`

Processes input CSS through synchronous plugins and returns Result#messages.

This property will work only with synchronous plugins. If processor contains any asynchronous plugin it will throw a error. You should use LazyResult#then() instead.

`lazy.processor`

Returns a Processor instance, that will be used for CSS transformations.

var lazy = postcss([cssnext, cssgrace]).process(css);
lazy.processor.plugins.length //=> 2

`lazy.opts`

Options from the Processor#process(css, opts) call that produced this Result instance.

postcss().process(css, opts).opts == opts;

`Result` class

Provides result of PostCSS transformations.

A Result instance is returned by Root#toResult(opts) or LazyResult#then() methods.

postcss([cssnext]).process(css).then(function (result1) {
    console.log(result1.css);
});
var result2 = postcss.parse(css).toResult();

`result.toString()`

Alias for Result#css property.

`result.warn(text, opts)`

Creates Warning and adds it to Result#messages.

var plugin = postcss.plugin('postcss-important', function () {
    return function (css, result) {
        css.eachDecl(function (decl) {
            if ( decl.important ) {
                result.warn('Try to avoid !important', { node: decl });
            }
        });
    }
});

postcss([plugin]).process(css).then(function (result) {
    result.warnings() //=> [{
                      //      plugin: 'postcss-important-warning',
                      //      text:   'Try to avoid !important'
                      //      node:  { type: 'decl', … }
                      //   }]
})

Arguments:

text (string): warning message. It will be used in text property of message object.
opts (object) optional: properties to message object.
- node: CSS node, that was a source of warning.
- plugin: name of plugin created this warning. Result#warn() will fill it automatically by plugin.postcssPlugin value.

`result.warnings()`

Returns warnings from plugins. It just a filters Warning instances from [Result#messages].

result.warnings().forEach(function (message) {
    console.log(message.toString());
});

`result.css`

A CSS string representing this Result’s 'Root instance.

postcss.parse('a{}').toResult().css //=> "a{}"

`result.map`

An instance of the SourceMapGenerator class from the source-map library, representing changes to the Result’s Root instance.

result.map.toJSON() //=> { version: 3, file: 'a.css', sources: ['a.css'], … }

This property will has a value only if the user does not want an inline source map. By default, PostCSS generates inline source maps, written directly into the processed CSS; so by default the map property will be empty.

An external source map will be generated — and assigned to map — only if the user has set the map.inline option to false, or if PostCSS was passed an external input source map.

if ( result.map ) {
    fs.writeFileSync(result.opts.to + '.map', result.map.toString());
}

`result.root`

Contains Root node after all transformations.

root.toResult().root == root;

`result.messages`

Contains messages from plugins. For example, warnings or custom messages to plugins communication.

Each message should has type and plugin properties.

postcss.plugin('postcss-min-browser', function () {
    return function (css, result) {
        var browsers = detectMinBrowsersByCanIUse(css);
        result.messages.push({
            type:    'min-browser',
            plugin:  'postcss-min-browser',
            browsers: browsers
        });
    }
})

You can add warning by Result#warn() and get all warnings by Result#warnings() method.

`result.processor`

Returns a Processor instance, that was used for this transformations.

result.processor.plugins.forEach(function (plugin) {
    if ( plugin.postcssPlugin == 'postcss-bad' ) {
        throw 'postcss-good is incompatible with postcss-bad';
    }
})

`result.opts`

Options from the Processor#process(css, opts) or Root#toResult(opts) call that produced this Result instance.

root.toResult(opts).opts == opts;

`Warning` class

Warning from plugins. It can be created by Result#warn().

if ( decl.important ) {
    result.warn('Try to avoid !important', { node: decl });
}

`warning.toString()`

Returns string with error position, message.

warning.toString() //=> 'postcss-important:a.css:10:4: Try to avoid !important'

`warning.text`

Contains warning message.

warning.text //=> 'Try to avoid !important'

`warning.plugin`

Contains plugin name created this warning. When you call Result#warn(), it will fill this property automatically.

warning.plugin //=> 'postcss-important'

`warning.node`

Contains CSS node, that was a source of warning.

warning.node.toString() //=> 'color: white !important'

`CssSyntaxError` class

CSS parser throw this error on broken CSS.

postcss.parse('a{') //=> CssSyntaxError

Custom parsers can throw this error on broken own custom syntax by Node#error() method.

throw node.error('Unknown variable', { plugin: 'postcss-vars' });

`error.toString()`

Returns string with error position, message and source code of broken part.

error.toString() //=> CssSyntaxError: app.css:1:1: Unclosed block
                 //   a {
                 //   ^

`error.showSourceCode(color)`

Returns a few lines of CSS source, which generates this error.

error.showSourceCode() //=>
                       //   a {
                       //     bad
                       //     ^
                       //   }

Arguments:

color (boolean) optional: should arrow will be colored to red by terminal color codes. By default, PostCSS will use process.stdout.isTTY and process.env.NODE_DISABLE_COLORS.

If CSS has input source map without sourceContent, this method will return empty string.

`error.message`

Contains full error text by GNU error format.

error.message //=> 'a.css:1:1: Unclosed block'

`error.reason`

Contains only error description.

error.reason //=> 'Unclosed block'

`error.plugin`

Contains PostCSS plugin name if error came not from CSS parser.

error.plugin //=> 'postcss-vars'

`error.file`

Contains absolute path to broken file, if use set from option to parser.

error.file //=> 'a.sass'

PostCSS will use input source map to detect origin place of error. If you wrote Sass file, then compile it to CSS and put to PostCSS, PostCSS will show position in origin Sass file.

If you need position in PostCSS input (for example, to debug previous compiler), you can use error.generated.file.

error.file           //=> 'a.sass'
error.generated.file //=> 'a.css'

`error.line`

Contains source line of error.

error.line //=> 2

PostCSS will use input source map to detect origin place of error. If you wrote Sass file, then compile it to CSS and put to PostCSS, PostCSS will show position in origin Sass file.

If you need position in PostCSS input (for example, to debug previous compiler), you can use error.generated.line.

error.line           //=> 2
error.generated.line //=> 4

`error.column`

Contains source column of error.

error.column //=> 1

PostCSS will use input source map to detect origin place of error. If you wrote Sass file, then compile it to CSS and put to PostCSS, PostCSS will show position in origin Sass file.

If you need position in PostCSS input (for example, to debug previous compiler), you can use error.generated.column.

error.column           //=> 1
error.generated.column //=> 4

`error.source`

Contains source code of broken file.

error.source //=> 'a {} b {'

PostCSS will use input source map to detect origin place of error. If you wrote Sass file, then compile it to CSS and put to PostCSS, PostCSS will show position in origin Sass file.

If you need position in PostCSS input (for example, to debug previous compiler), you can use error.generated.source.

error.source           //=> 'a { b {} }'
error.generated.column //=> 'a b { }'

Vendor module

Contains helpers for working with vendor prefixes.

var vendor = postcss.vendor;

`vendor.prefix(string)`

Returns the vendor prefix extracted from an input string.

postcss.vendor.prefix('-moz-tab-size') //=> '-moz-'

`vendor.unprefixed(string)`

Returns the input string stripped of its vendor prefix.

postcss.vendor.unprefixed('-moz-tab-size') //=> 'tab-size'

List module

Contains helpers for safely splitting lists of CSS values, preserving parentheses and quotes.

var list = postcss.list;

`list.space(string)`

Safely splits space-separated values (such as those for background, border-radius, and other shorthand properties).

postcss.list.space('1px calc(10% + 1px)') //=> ['1px', 'calc(10% + 1px)']

`list.comma(string)`

Safely splits comma-separated values (such as those for transition-* and background properties).

postcss.list.comma('black, linear-gradient(white, black)')
//=> ['black', 'linear-gradient(white, black)']

`Input` class

Represents the source CSS.

var root  = postcss.parse(css, { from: file });
var input = root.source.input;

`input.file`

The absolute path to the CSS source file defined with the from option.

var root  = postcss.parse(css, { from: 'a.css' });
root.source.input.file //=> '/home/ai/a.css'

`input.id`

The unique ID of the CSS source. This is used if the user did not enter a from options so PostCSS does not know about a file path.

var root  = postcss.parse(css);
root.source.input.file //=> undefined
root.source.input.id   //=> <input css 1>

`input.from`

The CSS source identifier. Contains input.file if the user set the from option, or input.id if she did not.

var root  = postcss.parse(css, { from: 'a.css' });
root.source.input.from //=> '/home/ai/a.css'

var root  = postcss.parse(css);
root.source.input.from //=> <input css 1>

`input.map`

Represents the input source map passed from a compilation step before PostCSS (for example, from the Sass compiler).

map.consumer() returns an instance of the SourceMapConsumer class from the source-map library.

root.source.input.map.consumer().sources //=> ['a.sass']

`input.origin(line, column)`

Reads the input source map and returns a symbol position in the input source (for example, in a Sass file that was compiled to CSS before being passed to PostCSS):

root.source.input.origin(1, 1) //=> { source: 'a.css', line: 3, column: 1 }

Nodes: common methods

All node classes have many common methods.

`node.type`

Returns a string representing the node’s type.

Possible values are root, atrule, rule, decl, or comment.

postcss.decl({ prop: 'color', value: 'black' }).type //=> 'decl'

`node.parent`

Returns the node’s parent node.

root.nodes[0].parent == root;

`node.source`

Returns the input source of the node, with the following properties:

node.source.input: An Input instance.
node.source.start: The starting position of the node’s source — line and column.
node.source.end: The ending position of the node’s source — line and column.

decl.source.input.from //=> '/home/ai/a.sass'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

The property is used in source map generation.

If you create a node manually (for example, with postcss.decl()), that node will not have a source property and will be absent from the source map. For this reason, plugin developer should consider cloning nodes to create new ones (in which case the new node’s source will reference the original, cloned node) or setting the source property manually.

// Bad
var prefixed = postcss.decl({ prop: '-moz-' + decl.prop, value: decl.value });

// Good
var prefixed = decl.clone({ prop: '-moz-' + decl.prop });

if ( atrule.name == 'add-link' ) {
    var rule = postcss.rule({ selector: 'a' }); // Rule has no source
    atrule.parent.insertBefore(atrule, rule);   // We add it because of atrule
    rule.source = atrule.source;                // So we copy source from atrule
}

`node.toString()`

Returns a CSS string representing the node.

postcss.rule({ selector: 'a' }).toString() //=> 'a {}''

`node.error(message, opts)`

Returns a CssSyntaxError instance that presents the original position of the node in the source, showing line and column numbers and also a small excerpt to facilitate debugging.

It will use an input source map, if present, to get the original position of the source, even from a previous compilation step (for example, from Sass compilation).

This method produces very useful error messages.

if ( !variables[name] ) {
    throw decl.error('Unknown variable ' + name, { plugin: 'postcss-vars' });
    // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
    // a
    //   color: $black
    //   ^
    //   background: white
}

Arguments:

message (string): error description.
opts (object) optional: options.
- plugin (string): plugin name, that created this error.

`node.next()` and `node.prev()`

Returns the next/previous child of the node’s parent; or returns undefined if the current node is the last/first child.

var annotation = decl.prev();
if ( annotation.type == 'comment' ) {
    readAnnotation( annotation.text );
}

`node.root()`

Returns the Root instance of the node’s tree.

root.nodes[0].nodes[0].root() == root

`node.removeSelf()`

Removes the node from its parent, and cleans the parent property in the node and its children.

if ( decl.prop.match(/^-webkit-/) ) {
    decl.removeSelf();
}

`node.replaceWith(otherNode)`

Inserts another node before the current node, and removes the current node.

if ( atrule.name == 'mixin' ) {
    atrule.replaceWith(mixinRules[atrule.params]);
}

Arguments:

otherNode: (Node): other node to replace current one.

`node.clone(props)`

Returns a clones of the node.

The resultant clone node and its (clone) children will have clean parent and code style properties.

var clonded = decl.clone({ prop: '-moz-' + decl.prop });
cloned.before     //=> undefined
cloned.parent     //=> undefined
cloned.toString() //=> -moz-transform: scale(0)

Arguments:

props (object) optional: new properties to override them in clone.

`node.cloneBefore(props)` and `node.cloneAfter(props)`

Shortcuts to clone the node and insert the resultant clone node before/after the current node.

decl.cloneBefore({ prop: '-moz-' + decl.prop });

Arguments:

props (object) optional: new properties to override them in clone.

`node.moveTo(newParent)`

Removes the node from its current parent and inserts it at the end of newParent.

This will clean the before and after code style properties from the node, and replace them with the indentation style of newParent. It will also clean the between property if newParent is in another Root.

atrule.moveTo(atrule.parent.parent);

Arguments:

newParent: (Container): container node where current node will be moved.

`node.moveBefore(otherNode)` and `node.moveAfter(otherNode)`

Removes the node from its current parent and inserts it into a new parent before/after otherNode.

This will also clean the node’s code style properties just as node.moveTo(newParent) does.

Arguments:

otherNode (Node): node which will be after/before current node after moving.

`node.style(prop, defaultType)`

Returns a code style property value. If the node is missing the code style property (because the node was manually built or cloned), PostCSS will try to autodetect the code style property by looking at other nodes in the tree.

var root = postcss.parse('a { background: white }');
root.nodes[0].append({ prop: 'color', value: 'black' });
root.nodes[0].nodes[1].style('before') //=> ' '

Arguments:

prop (string): name or code style property.
defaultType (string): name of default value. You can miss it if it is same with prop.

Containers: common methods

The Root, AtRule, and Rule container nodes have some common methods to help work with their children.

Note that all containers can store any content. If you write a rule inside a rule, PostCSS will parse it.

`container.nodes`

An array containing the container’s children.

var root = postcss.parse('a { color: black }');
root.nodes.length           //=> 1
root.nodes[0].selector      //=> 'a'
root.nodes[0].nodes[0].prop //=> 'color'

`container.first`

The container’s first child.

rule.first == rules.nodes[0];

`container.last`

The container’s last child.

rule.last == rule.nodes[rule.nodes.length - 1];

`container.index(child)`

Returns child’s index within the container’s nodes array.

rule.index( rule.nodes[2] ) //=> 2

Arguments:

child (Node): child of current container.

`container.every(callback)`

Returns true if callback returns a true for all of the container’s children.

var noPrefixes = rule.every(function (decl) {
    return decl.prop[0] != '-';
});

Arguments:

callback (function): iterator, that returns true of false.

`container.some(callback)`

Return true if callback returns a true value for (at least) one of the container’s children.

var hasPrefix = rule.some(function (decl) {
    return decl.prop[0] == '-';
});

Arguments:

callback (function): iterator, that returns true of false.

`container.each(callback)`

Iterates through the container’s immediate children, calling callback for each child.

Returning false within callback will break iteration.

var color;
rule.each(function (decl) {
    if ( decl.prop == 'color' ) {
        color = decl.value;
        return false;
    }
});

Arguments:

callback (function): iterator, that will receive node itself and an index.

Unlike the for {}-cycle or Array#forEach() this iterator is safe if you are mutating the array of child nodes during iteration. PostCSS will adjust the current index to match the mutations.

var root = postcss.parse('a { color: black; z-index: 1 }');
var rule = root.first;

for ( var i = 0; i < rule.nodes.length; i++ ) {
    var decl = rule.nodes[i];
    decl.cloneBefore({ prop: '-webkit-' + decl.prop });
    // Cycle will be infinite, because cloneBefore move current node
    // to next index
}

rule.each(function (decl) {
    decl.cloneBefore({ prop: '-webkit-' + decl.prop });
    // Will be executed only for color and z-index
});

container.each() only iterates through the container’s immediate children. If you need to recursively iterate through all the container’s nodes, use container.eachInside().

`container.eachInside(callback)`

Recursively iterates through the container’s children, those children’s children, etc., calling callback for each.

root.eachInside(function (node) {
    // Will be iterate through all nodes
});

Arguments:

callback (function): iterator, that will receive node itself and an index.

Like container.each(), this method is safe to use if you are mutating arrays during iteration.

If you only need to iterate through the container’s immediate children, use container.each().

`container.eachDecl([propFilter,] callback)`

Recursively iterates through all declaration nodes within the container, calling callback for each.

root.eachDecl(function (decl) {
    if ( decl.prop.match(/^-webkit-/) ) {
        decl.removeSelf();
    }
});

Arguments:

propFilter: (string|RegExp) optional: string or regular expression to filter declarations by property name.
- callback (function): iterator, that will receive node itself and an index.

If you pass a propFilter, only those declarations whose property matches propFilter will be iterated over.

// Make flat design
root.eachDecl('border-radius', function (decl) {
    decl.removeSelf();
});
root.eachDecl(/^background/, function (decl) {
    decl.value = takeFirstColorFromGradient(decl.value);
});

Like container.each(), this method is safe to use if you are mutating arrays during iteration.

`container.eachAtRule([nameFilter,] callback)`

Recursively iterates through all at-rule nodes within the container, calling callback for each.

root.eachAtRule(function (rule) {
    if ( rule.name.match(/^-webkit-/) ) rule.removeSelf();
});

Arguments:

nameFilter: (string|RegExp) optional: string or regular expression to filter at-rules by name.
- callback (function): iterator, that will receive node itself and an index.

If you pass a filter, only those at-rules whose name matches filter will be iterated over.

var first = false;
root.eachAtRule('charset', function (rule) {
    if ( !first ) {
        first = true;
    } else {
        rule.removeSelf();
    }
});

Like container.each(), this method is safe to use if you are mutating arrays during iteration.

`container.eachRule(callback)`

Recursively iterates through all rule nodes within the container, calling callback for each.

var selectors = [];
root.eachRule(function (rule) {
    selectors.push(rule.selector);
});
console.log('You CSS uses ' + selectors.length + ' selectors');

Arguments:

callback (function): iterator, that will receive node itself and an index.

Like container.each(), this method is safe to use if you are mutating arrays during iteration.

`container.eachComment(callback)`

Recursively iterates through all comment nodes within the container, calling callback for each.

root.eachComment(function (comment) {
    comment.removeSelf();
})

Arguments:

callback (function): iterator, that will receive node itself and an index.

Like container.each(), this method is safe to use if you are mutating arrays during iteration.

`container.replaceValues(pattern, opts, callback)`

Passes all declaration values within the container that match pattern through callback, replacing those values with the returned result of callback.

This method is useful if you are using a custom unit or function, so need to iterate through all values.

root.replaceValues(/\d+rem/, { fast: 'rem' }, function (string) {
    return 15 * parseInt(string) + 'px';
});

Arguments:

pattern (string|RegExp): pattern, that we need to replace.
opts (object) optional: options to speed up th search:
- props: An array of property names. The method will only search for values that match regexp within declarations of listed properties.
- fast: A string that will be used to narrow down values and speed up the regexp search. Searching every single value with a regexp can be slow; so if you pass a fast string, PostCSS will first check whether the value contains the fast string; and only if it does will PostCSS check that value against regexp. For example, instead of just checking for /\d+rem/ on all values, you can set fast: 'rem' to first check whether a value has the rem unit, and only if it does perform the regexp check.
callback (function|string): string to replace pattern or callback, that will return new value. Callback will receive the same arguments as those passed to a function parameter of String#replace.

`container.prepend(node)` and `container.append(node)`

Insert a new node to the start/end of the container.

var decl = postcss.decl({ prop: 'color', value: 'black' });
rule.append(decl);

Arguments:

node (Node|object|string): new node.

Because each node class is identifiable by unique properties, you can use the following shortcuts to create nodes in insert methods:

root.append({ name: '@charset', params: '"UTF-8"' }); // at-rule
root.append({ selector: 'a' });                       // rule
rule.append({ prop: 'color', value: 'black' });       // declaration
rule.append({ text: 'Comment' })                      // comment

Also you can use string with CSS of new element. But it will be a little bit slower, that shortcuts above.

root.append('a {}');
root.first.append('color: black; z-index: 1');

`container.insertBefore(oldNode, newNew)` and `container.insertAfter(oldNode, newNew)`

Insert newNode before/after oldNode within the container.

rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }));

Arguments:

oldNode (Node|number): child or child’s index.
node (Node|object|string): new node.

`container.remove(node)`

Removes node from the container, and the parent properties of node and its children.

rule.nodes.length  //=> 5
rule.remove(decl);
rule.nodes.length  //=> 4
decl.parent        //=> undefined

Arguments:

node (Node|number): child or child’s index.

`container.removeAll()`

Removes all children from the container, and cleans their parent properties.

rule.removeAll();
rule.nodes.length //=> 0

`Root` node

Represents a CSS file and contains all its parsed nodes.

var root = postcss.parse('a{color:black} b{z-index:2}');
root.type         //=> 'root'
root.nodes.length //=> 2

`root.toResult(opts)`

Returns a Result instance representing the root’s CSS.

var root1 = postcss.parse(css1, { from: 'a.css' });
var root2 = postcss.parse(css2, { from: 'b.css' });

root1.append(root2);
var result = root1.toResult({ to: 'all.css', map: true });

Arguments:

opts (object) optional: options:
- to: the path where you’ll put the output CSS file. You should always set to to generate correct source maps.
- map: an object of source map options.

`root.after`

The space symbols after the last child of root, such as \n at the end of a file.

var root = parse('a {}\nb { color: black }\n');
root.after //=> '\n'

This is a code style property.

`AtRule` node

Represents an at-rule.

This node will have a nodes property, representing its children, if it is followed in the CSS by a {} block.

var root = postcss.parse('@charset "UTF-8"; @media print {}');

var charset = root.first;
charset.type  //=> 'atrule'
charset.nodes //=> undefined

var media = root.last;
media.nodes   //=> []

`atrule.name`

The at-rule’s name. This is the identifier that immediately follows the @.

var root  = postcss.parse('@media print {}');
var media = root.first;
media.name //=> 'media'

`atrule.params`

The at-rule’s parameters. These are the values that follow the at-rule’s name but precede any {} block. The spec refers to this area as the at-rule’s “prelude”.

var root  = postcss.parse('@media print, screen {}');
var media = root.first;
media.params //=> '[print, screen]'

This value will be cleaned of comments. If the source at-rule’s prelude contained comments, those comments will be available in the _params.raw property.

If you have not changed the parameters, calling atrule.toString() will use the original raw value (comments and all).

var root  = postcss.parse('@media print, /**/ screen {}');
var media = root.first;
media.params      //=> '[print,  screen]'
media._params.raw //=> 'print, /**/ screen'
media.toString()  //=> '@media print, /**/ screen {}'

`atrule.before`

The space symbols before the at-rule.

The default value is \n, except for the first rule in a Root, whose before property is empty.

var root  = postcss.parse('@charset "UTF-8";\n@media print {}\n');
var media = root.last;
media.before //=> '\n'

This is a code style property.

`atrule.afterName`

The space symbols between the at-rule’s name and its parameters.

The default value is .

var root  = postcss.parse('@media\n  print,\n  screen {}\n');
var media = root.first;
media.afterName //=> '\n  '

This is a code style property.

`atrule.between`

The space symbols between the at-rule’s parameters and {, the block-opening curly brace.

The default value is .

var root  = postcss.parse('@media print, screen\n{}\n');
var media = root.first;
media.before //=> '\n'

This is a code style property.

`atrule.after`

The space symbols between the at-rule’s last child and }, the block-closing curly brace.

The default value is \n if the at-rule has children, and an empty string ('') if it does not.

var root  = postcss.parse('@media print {\n  a {}\n  }\n');
var media = root.first;
media.after //=> '\n  '

This is a code style property.

`atrule.semicolon`

true if at-rule’s last child declaration is followed by an (optional) semicolon.

undefined if the semicolon is omitted.

postcss.parse('@page{color:black}').first.semicolon  //=> undefined
postcss.parse('@page{color:black;}').first.semicolon //=> true

This is a code style property.

`Rule` node

Represents a CSS rule: a selector followed by a declaration block.

var root = postcss.parse('a{}');
var rule = root.first;
rule.type       //=> 'rule'
rule.toString() //=> 'a{}'

`rule.selector`

The rule’s full selector represented as a string. If there are multiple comma-separated selectors, the entire group will be included.

var root = postcss.parse('a, b { }');
var rule = root.first;
rule.selector //=> 'a, b'

This value will be cleaned of comments. If the source selector contained comments, those comments will be available in the _selector.raw property.

If you have not changed the selector, the result of rule.toString() will include the original raw selector value (comments and all).

var root = postcss.parse('a /**/ b {}');
var rule = root.first;
rule.selector      //=> 'a  b'
rule._selector.raw //=> 'a /**/ b'
rule.toString()    //=> 'a /**/ b {}'

`rule.selectors`

An array containing the rule’s individual selectors. Groups of selectors are split at commas.

var root = postcss.parse('a, b { }');
var rule = root.first;

rule.selector  //=> 'a, b'
rule.selectors //=> ['a', 'b']

rule.selectors = ['a', 'strong'];
rule.selector //=> 'a, strong'

`rule.before`

The space symbols before the rule.

The default value is \n, except for first rule in root, whose before property is empty.

var root = postcss.parse('a {}\nb {}\n');
var rule = root.last;
rule.before //=> '\n'

This is a code style property.

`rule.after`

The space symbols between the rule’s last child and }, the block-closing curly brace.

The default value is \n if rule has children and an empty string ('') if it does not.

var root = postcss.parse('@a {\n  color: black\n  }\n');
var rule = root.first;
root.after //=> '\n  '

This is a code style property.

`rule.semicolon`

true if rule’s last child declaration is followed by an (optional) semicolon.

undefined if the semicolon is omitted.

postcss.parse('a{color:black}').first.semicolon  //=> undefined
postcss.parse('a{color:black;}').first.semicolon //=> true

This is a code style property.

`Declaration` node

Represents a CSS declaration.

var root = postcss.parse('a { color: black }');
var decl = root.first.first;
decl.type       //=> 'decl'
decl.toString() //=> ' color: black'

`declaration.prop`

The declaration’s property name.

var root = postcss.parse('a { color: black }');
var decl = root.first.first;
decl.prop //=> 'color'

`declaration.value`

The declaration’s value.

var root = postcss.parse('a { color: black }');
var decl = root.first.first;
decl.value //=> 'black'

This value will be cleaned of comments. If the source value contained comments, those comments will be available in the _value.raw property.

If you have not changed the value, the result of decl.toString() will include the original raw value (comments and all).

var root = postcss.parse('a { border-radius: 3px /**/ 0 }');
var decl = root.first.first;
decl.value      //=> '3px  0'
decl._value.raw //=> '3px /**/ 0'
decl.toString() //=> ' border-radius: 3px /**/ 0'

`declaration.before`

The space symbols before the declaration.

Default value is \n .

var root = postcss.parse('a {\n  color: black\n}\n');
var decl = root.first.first;
decl.before //=> '\n  '

This is a code style property.

`declaration.between`

The symbols between the declaration’s property and its value.

Default value is : .

var root = postcss.parse('a { color/**/: black }');
var decl = root.first.first;
decl.between //=> '/**/: '

This is a code style property.

`declaration.important`

true if the declaration has an !important annotation.

var root = postcss.parse('a { color: black !important; color: white }');
root.first.first.important //=> true
root.first.last.important  //=> undefined

If there are comments between the declaration’s value and its !important annotation, they will be available in the _important property.

var root = postcss.parse('a { color: black /**/ !important }');
root.first.first._important //=> ' /**/ !important'

`Comment` node

Represents a comment between declarations or statements (rule and at-rules). Comments inside selectors, at-rules parameters, or declaration values will be stored in the raw properties explained above.

var root    = postcss.parse('a { color: /* inner */ black; /* outer */ }');
var decl    = root.first.first;
var comment = root.first.last;

comment.type //=> 'comment'
decl.between //=> ': /* inner */'

`comment.text`

The comment’s text.

var root    = postcss.parse('/* Empty file */');
var comment = root.first;
var comment.text //=> 'Empty file'

`comment.left` and `comment.right`

The space symbols before/after the comment’s text.

Default value is .

var root  = postcss.parse('/* long */ /*short*/');
var long  = root.first;
var short = root.last;

long.left  //=> ' '
short.left //=> ''

This is a code style property.

`comment.before`

The space symbols before the comment.

Default value is \n.

var root    = postcss.parse('a {\n  /**/}\n');
var comment = root.first.first;
comment.before //=> '\n  '

This is a code style property.

Files

API.md

Latest commit

History

API.md

File metadata and controls

PostCSS API

postcss function

postcss(plugins)

postcss.parse(css, opts)

postcss.plugin(name, initializer)

postcss.root(props)

postcss.atRule(props)

postcss.rule(props)

postcss.decl(props)

postcss.comment(props)

postcss.vendor

postcss.list

Processor class

processor.use(plugin)

processor.process(css, opts)

processor.plugins

processor.version

LazyResult class

lazy.then(onFulfilled, onRejected)

lazy.catch(onRejected)

lazy.toString()

lazy.css

lazy.map

lazy.root

lazy.warnings()

lazy.messages

lazy.processor

lazy.opts

Result class

result.toString()

result.warn(text, opts)

result.warnings()

result.css

result.map

result.root

result.messages

result.processor

result.opts

Warning class

warning.toString()

warning.text

warning.plugin

warning.node

CssSyntaxError class

error.toString()

error.showSourceCode(color)

error.message

error.reason

error.plugin

error.file

error.line

error.column

error.source

Vendor module

vendor.prefix(string)

vendor.unprefixed(string)

List module

list.space(string)

list.comma(string)

Input class

input.file

input.id

input.from

input.map

input.origin(line, column)

Nodes: common methods

node.type

node.parent

node.source

node.toString()

node.error(message, opts)

node.next() and node.prev()

node.root()

node.removeSelf()

`postcss` function

`postcss(plugins)`

`postcss.parse(css, opts)`

`postcss.plugin(name, initializer)`

`postcss.root(props)`

`postcss.atRule(props)`

`postcss.rule(props)`

`postcss.decl(props)`

`postcss.comment(props)`

`postcss.vendor`

`postcss.list`

`Processor` class

`processor.use(plugin)`

`processor.process(css, opts)`

`processor.plugins`

`processor.version`

`LazyResult` class

`lazy.then(onFulfilled, onRejected)`

`lazy.catch(onRejected)`

`lazy.toString()`

`lazy.css`

`lazy.map`

`lazy.root`

`lazy.warnings()`

`lazy.messages`

`lazy.processor`

`lazy.opts`

`Result` class

`result.toString()`

`result.warn(text, opts)`

`result.warnings()`

`result.css`

`result.map`

`result.root`

`result.messages`

`result.processor`

`result.opts`

`Warning` class

`warning.toString()`

`warning.text`

`warning.plugin`

`warning.node`

`CssSyntaxError` class

`error.toString()`

`error.showSourceCode(color)`

`error.message`

`error.reason`

`error.plugin`

`error.file`

`error.line`

`error.column`

`error.source`

`vendor.prefix(string)`

`vendor.unprefixed(string)`

`list.space(string)`

`list.comma(string)`

`Input` class

`input.file`

`input.id`

`input.from`

`input.map`

`input.origin(line, column)`

`node.type`

`node.parent`

`node.source`

`node.toString()`

`node.error(message, opts)`

`node.next()` and `node.prev()`

`node.root()`

`node.removeSelf()`

`node.replaceWith(otherNode)`

`node.clone(props)`

`node.cloneBefore(props)` and `node.cloneAfter(props)`

`node.moveTo(newParent)`

`node.moveBefore(otherNode)` and `node.moveAfter(otherNode)`

`node.style(prop, defaultType)`

`container.nodes`

`container.first`

`container.last`

`container.index(child)`