Root - Documentation

Constructor

new Root()

Source:

root.es6, line 13

Example

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

Extends

Container

Members

first :Node

Source:

container.es6, line 568

Inherited From:

Container#first

The container’s first child.

Type:

Node

Example

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

last :Node

Source:

container.es6, line 581

Inherited From:

Container#last

The container’s last child.

Type:

Node

Example

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

nodes :Array.<Node>

Source:

container.es6, line 635

Overrides:

Container#nodes

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:

node.es6, line 433

Inherited From:

Node#parent

The node’s parent node.

Type:

Container

Example

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

raws :object

Source:

node.es6, line 478

Inherited From:

Node#raws

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:

node.es6, line 441

Inherited From:

Node#source

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:

source

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:

node.es6, line 423

Overrides:

Container#type

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:

node.es6, line 309

Inherited From:

Node#after

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:

container.es6, line 323

Inherited From:

Container#append

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:

node.es6, line 292

Inherited From:

Node#before

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

cleanRaws(keepBetweenopt) → {undefined}

Source:

node.es6, line 389

Inherited From:

Node#cleanRaws

Clear the code style properties for the node and its children.

Example

node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined

Parameters:

Name	Type	Attributes	Description
`keepBetween`	boolean	<optional>	Keep the raws.between symbols.

Returns:

Type: undefined

clone(overridesopt) → {Node}

Source:

node.es6, line 179

Inherited From:

Node#clone

Returns an exact clone of the node.

The resulting cloned node and its (cloned) children will retain code style properties.

Example

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
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:

node.es6, line 212

Inherited From:

Node#cloneAfter

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:

node.es6, line 198

Inherited From:

Node#cloneBefore

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>	Mew properties to override in the clone.

Returns:

New node

Type: Node

each(callback) → {false|undefined}

Source:

container.es6, line 63

Inherited From:

Container#each

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 (const 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:

node.es6, line 84

Inherited From:

Node#error

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

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:

container.es6, line 523

Inherited From:

Container#every

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:

container.es6, line 552

Inherited From:

Container#index

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:

container.es6, line 407

Inherited From:

Container#insertAfter

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:

container.es6, line 381

Inherited From:

Container#insertBefore

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}

Source:

node.es6, line 256

Inherited From:

Node#next

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:

container.es6, line 351

Inherited From:

Container#prepend

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}

Source:

node.es6, line 274

Inherited From:

Node#prev

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:

node.es6, line 358

Inherited From:

Node#raw

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:

node.es6, line 135

Inherited From:

Node#remove

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:

container.es6, line 464

Inherited From:

Container#removeAll

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:

container.es6, line 438

Overrides:

Container#removeChild

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:

container.es6, line 496

Inherited From:

Container#replaceValues

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:

node.es6, line 230

Inherited From:

Node#replaceWith

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>	Mode(s) to replace current one.

Returns:

Current node to methods chain.

Type: Node

root() → {Root}

Source:

node.es6, line 371

Inherited From:

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

container.es6, line 538

Inherited From:

Container#some

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}

Source:

root.es6, line 63

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 `to` and `map` keys.

Returns:

Result with current root’s CSS.

Type: Result

toString(stringifieropt) → {string}

Source:

node.es6, line 154

Inherited From:

Node#toString

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:

container.es6, line 106

Inherited From:

Container#walk

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:

container.es6, line 256

Inherited From:

Container#walkAtRules

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:

container.es6, line 295

Inherited From:

Container#walkComments

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:

container.es6, line 156

Inherited From:

Container#walkDecls

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:

container.es6, line 202

Inherited From:

Container#walkRules

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:

node.es6, line 118

Inherited From:

Node#warn

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

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