Container

Container

The Root, AtRule, and Rule container nodes inherit 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.

Constructor

(abstract) new Container()

Source:

Extends

Members

first :Node

Source:

The container’s first child.

Type:
Example
rule.first == rules.nodes[0];

last :Node

Source:

The container’s last child.

Type:
Example
rule.last == rule.nodes[rule.nodes.length - 1];

nodes :Array.<Node>

Source:

an array containing the container’s children

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

parent :Container

Source:
Inherited From:

the node’s parent node.

Type:
Example
root.nodes[0].parent == root;

raws :object

Source:
Inherited From:

Information to generate byte-to-byte equal node string as it was in the origin input.

Every parser saves its own properties, but the default CSS parser uses:

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

PostCSS cleans selectors, declaration values and at-rule parameters from comments and extra spaces, but it stores origin content in raws properties. As such, if you don’t change a declaration’s value, PostCSS will use the raw value with comments.

Type:
  • object
Example
const root = postcss.parse('a {\n  color:black\n}')
root.first.first.raws //=> { before: '\n  ', between: ':' }

source :source

Source:
Inherited From:

the input source of the node

The property is used in source map generation.

If you create a node manually (e.g., 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
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
});

// Good
const prefixed = decl.clone({ prop: '-moz-' + decl.prop });
if ( atrule.name == 'add-link' ) {
  const rule = postcss.rule({ selector: 'a', source: atrule.source });
  atrule.parent.insertBefore(atrule, rule);
}
Type:
Example
decl.source.input.from //=> '/home/ai/a.sass'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

type :string

Source:
Inherited From:

String representing the node’s type. Possible values are root, atrule, rule, decl, or comment.

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

Methods

append(…children) → {Node}

Source:

Inserts new nodes to the start of the container.

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

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

root.append('a {}');
root.first.append('color: black; z-index: 1');
Parameters:
Name Type Attributes Description
children Node | object | string | Array.<Node> <repeatable>

new nodes

Returns:

this node for methods chain

Type
Node

clone(overridesopt) → {Node}

Source:
Inherited From:

Returns a clone of the node.

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

Example
const cloned = decl.clone({ prop: '-moz-' + decl.prop });
cloned.raws.before  //=> undefined
cloned.parent       //=> undefined
cloned.toString()   //=> -moz-transform: scale(0)
Parameters:
Name Type Attributes Description
overrides object <optional>

new properties to override in the clone.

Returns:

clone of the node

Type
Node

cloneAfter(overridesopt) → {Node}

Source:
Inherited From:

Shortcut to clone the node and insert the resulting cloned node after the current node.

Parameters:
Name Type Attributes Description
overrides object <optional>

new properties to override in the clone.

Returns:
  • new node
Type
Node

cloneBefore(overridesopt) → {Node}

Source:
Inherited From:

Shortcut to clone the node and insert the resulting cloned node before the current node.

Example
decl.cloneBefore({ prop: '-moz-' + decl.prop });
Parameters:
Name Type Attributes Description
overrides object <optional>

new properties to override in the clone.

Returns:
  • new node
Type
Node

each(callback) → {false|undefined}

Source:

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

Returning false in the callback will break iteration.

This method only iterates through the container’s immediate children. If you need to recursively iterate through all the container’s descendant nodes, use Container#walk.

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.

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

for ( let decl of rule.nodes ) {
    decl.cloneBefore({ prop: '-webkit-' + decl.prop });
    // Cycle will be infinite, because cloneBefore moves the current node
    // to the next index
}

rule.each(decl => {
    decl.cloneBefore({ prop: '-webkit-' + decl.prop });
    // Will be executed only for color and z-index
});
Parameters:
Name Type Description
callback childIterator

iterator receives each node and index

Returns:

returns false if iteration was broke

Type
false | undefined

error(message, optsopt) → {CssSyntaxError}

Source:
Inherited From:

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 (e.g., from Sass compilation).

This method produces very useful error messages.

Example
if ( !variables[name] ) {
  throw decl.error('Unknown variable ' + name, { word: name });
  // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
  //   color: $black
  // a
  //          ^
  //   background: white
}
Parameters:
Name Type Attributes Description
message string

error description

opts object <optional>

options

Properties
Name Type Description
plugin string

plugin name that created this error. PostCSS will set it automatically.

word string

a word inside a node’s string that should be highlighted as the source of the error

index number

an index inside a node’s string that should be highlighted as the source of the error

Returns:

error object to throw it

Type
CssSyntaxError

every(condition) → {boolean}

Source:

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

Example
const noPrefixes = rule.every(i => i.prop[0] !== '-');
Parameters:
Name Type Description
condition childCondition

iterator returns true or false.

Returns:

is every child pass condition

Type
boolean

index(child) → {number}

Source:

Returns a child’s index within the Container#nodes array.

Example
rule.index( rule.nodes[2] ) //=> 2
Parameters:
Name Type Description
child Node

child of the current container.

Returns:

child index

Type
number

insertAfter(exist, add) → {Node}

Source:

Insert new node after old node within the container.

Parameters:
Name Type Description
exist Node | number

child or child’s index

add Node | object | string | Array.<Node>

new node

Returns:

this node for methods chain

Type
Node

insertBefore(exist, add) → {Node}

Source:

Insert new node before old node within the container.

Example
rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }));
Parameters:
Name Type Description
exist Node | number

child or child’s index.

add Node | object | string | Array.<Node>

new node

Returns:

this node for methods chain

Type
Node

moveAfter(otherNode) → {Node}

Source:
Inherited From:

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

This will also clean the node’s code style properties just as it would in Node#moveTo.

Parameters:
Name Type Description
otherNode Node

node that will be after current node

Returns:

current node to methods chain

Type
Node

moveBefore(otherNode) → {Node}

Source:
Inherited From:

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

This will also clean the node’s code style properties just as it would in Node#moveTo.

Parameters:
Name Type Description
otherNode Node

node that will be before current node

Returns:

current node to methods chain

Type
Node

moveTo(newParent) → {Node}

Source:
Inherited From:

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

This will clean the before and after code Node#raws data 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.

Example
atrule.moveTo(atrule.root());
Parameters:
Name Type Description
newParent Container

container node where the current node will be moved

Returns:

current node to methods chain

Type
Node

next() → {Node|undefined}

Source:
Inherited From:

Returns the next child of the node’s parent. Returns undefined if the current node is the last child.

Example
if ( comment.text === 'delete next' ) {
  const next = comment.next();
  if ( next ) {
    next.remove();
  }
}
Returns:

next node

Type
Node | undefined

prepend(…children) → {Node}

Source:

Inserts new nodes to the end of the container.

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

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

root.append('a {}');
root.first.append('color: black; z-index: 1');
Parameters:
Name Type Attributes Description
children Node | object | string | Array.<Node> <repeatable>

new nodes

Returns:

this node for methods chain

Type
Node

prev() → {Node|undefined}

Source:
Inherited From:

Returns the previous child of the node’s parent. Returns undefined if the current node is the first child.

Example
const annotation = decl.prev();
if ( annotation.type == 'comment' ) {
 readAnnotation(annotation.text);
}
Returns:

previous node

Type
Node | undefined

raw(prop, defaultTypeopt) → {string}

Source:
Inherited From:

Returns a Node#raws 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.

Example
const root = postcss.parse('a { background: white }');
root.nodes[0].append({ prop: 'color', value: 'black' });
root.nodes[0].nodes[1].raws.before   //=> undefined
root.nodes[0].nodes[1].raw('before') //=> ' '
Parameters:
Name Type Attributes Description
prop string

name of code style property

defaultType string <optional>

name of default value, it can be missed if the value is the same as prop

Returns:

code style value

Type
string

remove() → {Node}

Source:
Overrides:

Removes the node from its parent and cleans the parent properties from the node and its children.

Example
if ( decl.prop.match(/^-webkit-/) ) {
  decl.remove();
}
Returns:

node to make calls chain

Type
Node

removeAll() → {Node}

Source:

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

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

this node for methods chain

Type
Node

removeChild(child) → {Node}

Source:

Removes node from the container and cleans the parent properties from the node and its children.

Example
rule.nodes.length  //=> 5
rule.removeChild(decl);
rule.nodes.length  //=> 4
decl.parent        //=> undefined
Parameters:
Name Type Description
child Node | number

child or child’s index

Returns:

this node for methods chain

Type
Node

replaceValues(pattern, opts, callback) → {Node}

Source:

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.

Example
root.replaceValues(/\d+rem/, { fast: 'rem' }, string => {
  return 15 * parseInt(string) + 'px';
});
Parameters:
Name Type Description
pattern string | RegExp

replace pattern

opts object

options to speed up the search

Properties
Name Type Description
props string | Array.<string>

an array of property names

fast string

string that’s used to narrow down values and speed up the regexp search

callback function | string

string to replace pattern or callback that returns a new value. The callback will receive the same arguments as those passed to a function parameter of String#replace.

Returns:

this node for methods chain

Type
Node

replaceWith(…nodes) → {Node}

Source:
Inherited From:

Inserts node(s) before the current node and removes the current node.

Example
if ( atrule.name == 'mixin' ) {
  atrule.replaceWith(mixinRules[atrule.params]);
}
Parameters:
Name Type Attributes Description
nodes Node <repeatable>

node(s) to replace current one

Returns:

current node to methods chain

Type
Node

root() → {Root}

Source:
Inherited From:

Finds the Root instance of the node’s tree.

Example
root.nodes[0].nodes[0].root() === root
Returns:

root parent

Type
Root

some(condition) → {boolean}

Source:

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

Example
const hasPrefix = rule.some(i => i.prop[0] === '-');
Parameters:
Name Type Description
condition childCondition

iterator returns true or false.

Returns:

is some child pass condition

Type
boolean

toString(stringifieropt) → {string}

Source:
Inherited From:

Returns a CSS string representing the node.

Example
postcss.rule({ selector: 'a' }).toString() //=> "a {}"
Parameters:
Name Type Attributes Description
stringifier stringifier | syntax <optional>

a syntax to use in string generation

Returns:

CSS string of this node

Type
string

walk(callback) → {false|undefined}

Source:

Traverses the container’s descendant nodes, calling callback for each node.

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.

Example
root.walk(node => {
  // Traverses all descendant nodes.
});
Parameters:
Name Type Description
callback childIterator

iterator receives each node and index

Returns:

returns false if iteration was broke

Type
false | undefined

walkAtRules(nameopt, callback) → {false|undefined}

Source:

Traverses the container’s descendant nodes, calling callback for each at-rule node.

If you pass a filter, iteration will only happen over at-rules that have matching names.

Like Container#each, this method is safe to use if you are mutating arrays during iteration.

Example
root.walkAtRules(rule => {
  if ( isOld(rule.name) ) rule.remove();
});

let first = false;
root.walkAtRules('charset', rule => {
  if ( !first ) {
    first = true;
  } else {
    rule.remove();
  }
});
Parameters:
Name Type Attributes Description
name string | RegExp <optional>

string or regular expression to filter at-rules by name

callback childIterator

iterator receives each node and index

Returns:

returns false if iteration was broke

Type
false | undefined

walkComments(callback) → {false|undefined}

Source:

Traverses the container’s descendant nodes, calling callback for each comment node.

Like Container#each, this method is safe to use if you are mutating arrays during iteration.

Example
root.walkComments(comment => {
  comment.remove();
});
Parameters:
Name Type Description
callback childIterator

iterator receives each node and index

Returns:

returns false if iteration was broke

Type
false | undefined

walkDecls(propopt, callback) → {false|undefined}

Source:

Traverses the container’s descendant nodes, calling callback for each declaration node.

If you pass a filter, iteration will only happen over declarations with matching properties.

Like Container#each, this method is safe to use if you are mutating arrays during iteration.

Example
root.walkDecls(decl => {
  checkPropertySupport(decl.prop);
});

root.walkDecls('border-radius', decl => {
  decl.remove();
});

root.walkDecls(/^background/, decl => {
  decl.value = takeFirstColorFromGradient(decl.value);
});
Parameters:
Name Type Attributes Description
prop string | RegExp <optional>

string or regular expression to filter declarations by property name

callback childIterator

iterator receives each node and index

Returns:

returns false if iteration was broke

Type
false | undefined

walkRules(selectoropt, callback) → {false|undefined}

Source:

Traverses the container’s descendant nodes, calling callback for each rule node.

If you pass a filter, iteration will only happen over rules with matching selectors.

Like Container#each, this method is safe to use if you are mutating arrays during iteration.

Example
const selectors = [];
root.walkRules(rule => {
  selectors.push(rule.selector);
});
console.log(`Your CSS uses ${selectors.length} selectors`);
Parameters:
Name Type Attributes Description
selector string | RegExp <optional>

string or regular expression to filter rules by selector

callback childIterator

iterator receives each node and index

Returns:

returns false if iteration was broke

Type
false | undefined

warn(result, text, optsopt) → {Warning}

Source:
Inherited From:

This method is provided as a convenience wrapper for Result#warn.

Example
const plugin = postcss.plugin('postcss-deprecated', () => {
  return (root, result) => {
    root.walkDecls('bad', decl => {
      decl.warn(result, 'Deprecated property bad');
    });
  };
});
Parameters:
Name Type Attributes Description
result Result

the Result instance that will receive the warning

text string

warning message

opts object <optional>

options

Properties
Name Type Description
plugin string

plugin name that created this warning. PostCSS will set it automatically.

word string

a word inside a node’s string that should be highlighted as the source of the warning

index number

an index inside a node’s string that should be highlighted as the source of the warning

Returns:

created warning object

Type
Warning