Constructor
new Root()
Example
const root = postcss.parse('a{color:black} b{z-index:2}');
root.type //=> 'root'
root.nodes.length //=> 2
Extends
Members
first :Node
- Source:
- Inherited From:
The container’s first child.
Type:
Example
rule.first == rules.nodes[0];
last :Node
- Source:
- Inherited From:
The container’s last child.
Type:
Example
rule.last == rule.nodes[rule.nodes.length - 1];
nodes :Array.<Node>
- Source:
- Overrides:
an array containing the container’s children
Type:
- Array.<Node>
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:
- Overrides:
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:
after
: the space symbols after the last child to the end of file.semicolon
: is the last child has an (optional) semicolon.
Type:
- object
Example
postcss.parse('a {}\n').raws //=> { after: '\n' }
postcss.parse('a {}').raws //=> { after: '' }
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:
- Overrides:
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
after(add) → {Node}
- Source:
- Inherited From:
Insert new node after current node to current node’s parent.
Just alias for node.parent.insertAfter(node, add)
.
Example
decl.after('color: black');
Parameters:
Name | Type | Description |
---|---|---|
add |
Node | object | string | Array.<Node> | new node |
Returns:
this node for methods chain.
- Type
- Node
append(…children) → {Node}
- Source:
- Inherited From:
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.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
before(add) → {Node}
- Source:
- Inherited From:
Insert new node before current node to current node’s parent.
Just alias for node.parent.insertBefore(node, add)
.
Example
decl.before('content: ""');
Parameters:
Name | Type | Description |
---|---|---|
add |
Node | object | string | Array.<Node> | new node |
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:
- Inherited From:
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
|
Returns:
error object to throw it
- Type
- CssSyntaxError
every(condition) → {boolean}
- Source:
- Inherited From:
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:
- Inherited From:
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:
- Inherited From:
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:
- Inherited From:
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
next() → {Node|undefined}
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:
- Inherited From:
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.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}
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}
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:
- Inherited From:
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:
- Inherited From:
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:
- Overrides:
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:
- Inherited From:
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
|
|||||||||
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 |
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}
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:
- Inherited From:
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
toResult(optsopt) → {Result}
Returns a Result instance representing the root’s CSS.
Example
const root1 = postcss.parse(css1, { from: 'a.css' });
const root2 = postcss.parse(css2, { from: 'b.css' });
root1.append(root2);
const result = root1.toResult({ to: 'all.css', map: true });
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
opts |
processOptions |
<optional> |
options with only |
Returns:
result with current root’s CSS
- Type
- Result
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:
- Inherited From:
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:
- Inherited From:
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:
- Inherited From:
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:
- Inherited From:
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:
- Inherited From:
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}
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
|
Returns:
created warning object
- Type
- Warning