postcss/docs/api.md

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): list of PostCSS plugins to be included as processors.

Plugins can also be included 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 a PostCSS plugin with a standard API.

var remove = postcss.plugin('postcss-remove', function (opts) {
    var filter = opts.prop || 'z-index';
    return function (css, result) {
        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'

The plugin function receives 2 arguments: Root node and Result instance. Then it should mutate the passed Root node. Alternatively, create a new Root node and override the result.root property.

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

Asynchronous plugins 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();
            });
        });
    };
});

Add warnings using the 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 });
            }
        });
    };
});

Send data to next plugins using the 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. 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. It 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 the 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 Plugins 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 applied 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. Optionally, send Result instance and the processor will take the existing [Root] parser from it.
• opts (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 a plugin throws an 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, converts 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 plugins 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 plugins it will throw an 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 plugins it will throw an 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 calls [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 plugins 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 plugins it will throw an error. You should use LazyResult#then() instead.

lazy.processor

Returns a Processor instance, which 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 the result of the 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 that created this warning. Result#warn() will fill it automatically with plugin.postcssPlugin value.

result.warnings()

Returns warnings from plugins. 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 have 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. The map property will be empty by default.

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 have 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
        });
    };
});

Add a warning using Result#warn() and get all warnings using Result#warnings() method.

result.processor

Returns the Processor instance used for this transformation.

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 using 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 name of plugin that created this warning. When you call Result#warn(), it will fill this property automatically.

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

warning.node

Contains CSS node that caused warning.

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

CssSyntaxError class

CSS parser throws this error for broken CSS.

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

Custom parsers can throw this error for broken custom syntax using the 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 that caused 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 an 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 did not come from CSS parser.

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

PostCSS will fill it automatically.

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 the original error location. If you wrote a Sass file, then compiled it to CSS and parsed it with PostCSS, PostCSS will show the original position in the Sass file.

If you need position in PostCSS input (for example, to debug previous compiler), 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 the original error location. If you wrote a Sass file, then compiled it to CSS and parsed it with PostCSS, PostCSS will show the original position in the Sass file.

If you need position in PostCSS input (for example, to debug previous compiler), 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 the original error location. If you wrote a Sass file, then compiled it to CSS and parsed it with PostCSS, PostCSS will show the original position in the Sass file.

If you need position in PostCSS input (for example, to debug previous compiler), 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 the original error location. If you wrote a Sass file, then compiled it to CSS and parsed it with PostCSS, PostCSS will show the original position in the Sass file.

If you need position in PostCSS input (for example, to debug previous compiler), 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. Used if from option is not provided (because PostCSS does not know the 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 he/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, the 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.raw

Contains information to generate byte-to-byte equal node string as it was in origin input.

Every parser saves its own properties, but default CSS parser use:

• before: the space symbols before node. It stores also any non-standard symbols before declaration like _ from IE hack.
• after: the space symbols after last child of node to the end of the node.
• between: the symbols between property and value for declarations, selector and { for rules, last parameter and { for at-rules.
• semicolon: contains true if last child has (optional) semicolon.
• afterName: the space between at-rule’s name and parameters.
• left: the space symbols between /* and comment’s text.
• right: the space symbols between comment’s text and */.
• important: the content of important statement, if it is not just !important.

PostCSS cleans selectors, declaration’s values and at-rule’s parameters from comments and extra spaces. But PostCSS stores origin content in raw properties. So, if you will not change declaration value, PostCSS will use raw value with comments.

node.toString()

Returns a CSS string representing the node.

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

node.error(message, opts)

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

If present, an input source map will be used 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);
    // 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. PostCSS will set it automatically.

See also Result#warn() for warnings.

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(...otherNodes)

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

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

node.clone(props)

Returns a clone of the node.

The resulting cloned node and its (cloned) children will have clean parent and code style properties.

var cloned = 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)

Shortcut to clone the node and insert the resulting cloned 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. It can be easily missed if the value is the same as 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 or 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, returns true or 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([selectorFilter,] 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:

• selectorFilter: (string|RegExp) optional: string or regular expression to filter rules by selector.
• callback (function): iterator, that will receive node itself and an index.

If you pass a selectorFilter, only those rules whose selector matches selectorFilter will be iterated over.

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 and 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 used to narrow down values and speed up the regexp search. Searching every single value with a regexp can be slow. 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, 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(...nodes) and container.append(...nodes)

Inserts new nodes to the start/end of the container.

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

var decl1 = postcss.decl({ prop: 'color', value: 'black' });
var decl2 = postcss.decl({ prop: 'background-color', value: 'white' });
rule.prepend(decl1, decl2);

Arguments:

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

Because each node class is identifiable by unique properties, 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

A string containing the CSS of the new element can also be used. This approach is slower than the above shortcuts.

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.

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]'

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'

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'

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'

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

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 Node#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'