postcss

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

let postcss = require('postcss')

postcss(plugins).process(css, { from, to }).then(result => {
  console.log(result.css)
})

Returns Processor.

postcss.AcceptedPlugin

Type: Object | OldPlugin<any> | Plugin | PluginCreator<any> | Processor | TransformCallback.

postcss.Builder

postcss.Helpers

Type: Object & Postcss.

postcss.JSONHydrator

Returns Node.

postcss.OldPlugin

Returns Transformer.

postcss.Parser

Returns RootNode.

postcss.PluginCreator

Returns Processor | Plugin.

postcss.Postcss

Type: typeof postcss.

postcss.RuleProps

Type: ContainerProps & Object & (Object | Object).

postcss.SourceMap

Type: Object & SourceMapGenerator.

postcss.Stringifier

postcss.TransformCallback

Returns void | Promise<void>.

postcss.Transformer

Returns void | Promise<void>.

postcss.atRule

Creates a new AtRule node.

Returns AtRule_.

postcss.comment

Creates a new Comment node.

Returns Comment_.

postcss.decl

Creates a new Declaration node.

Returns Declaration_.

postcss.document

Creates a new Document node.

Returns Document_.

postcss.fromJSON

Rehydrate a JSON AST (from Node#toJSON) back into the AST classes.

const json = root.toJSON()
// save to file, send by network, etc
const root2  = postcss.fromJSON(json)

Returns Node.

postcss.list

Type: List.

postcss.parse

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

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

Returns Root.

postcss.root

Creates a new Root node.

Returns Root.

postcss.rule

Creates a new Rule node.

Returns Rule.

postcss.stringify

Default function to convert a node tree into a CSS string.

AtRule

Represents an at-rule.

Once (root, { AtRule }) {
  let media = new AtRule({ name: 'media', params: 'print' })
  media.append(…)
  root.append(media)
}

If it’s followed in the CSS by a {} block, this node will have a nodes property representing its children.

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

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

const media = root.last
media.nodes   //=> []

AtRule#after()

Insert new node after current node to current node’s parent.

Just alias for node.parent.insertAfter(node, add).

decl.after('color: black')

Returns AtRule.

AtRule#append()

Inserts new nodes to the end of the container.

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ 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')

Returns AtRule.

AtRule#assign()

It assigns properties to an existing node instance.

decl.assign({ prop: 'word-wrap', value: 'break-word' })

Returns AtRule.

AtRule#before()

Insert new node before current node to current node’s parent.

Just alias for node.parent.insertBefore(node, add).

decl.before('content: ""')

Returns AtRule.

AtRule#cleanRaws()

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

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

AtRule#clone()

It creates clone of an existing node, which includes all the properties and their values, that includes raws but not type.

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

Returns AtRule.

AtRule#cloneAfter()

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

Returns AtRule.

AtRule#cloneBefore()

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

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

Returns AtRule.

AtRule#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.

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

Returns void | false.

AtRule#error()

It creates an instance of the class CssSyntaxError and parameters passed to this method are assigned to the error instance.

The error instance will have description for the error, original position of the node in the source, showing line and column number.

If any previous map is present, it would be used to get original position of the source.

The Previous Map here is referred to the source map generated by previous compilation, example: Less, Stylus and Sass.

This method returns the error instance instead of throwing it.

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
}

Returns CssSyntaxError_.

AtRule#every()

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

const noPrefixes = rule.every(i => i.prop[0] !== '-')

Returns boolean.

AtRule#index()

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

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

Returns number.

AtRule#insertAfter()

Insert new node after old node within the container.

Returns AtRule.

AtRule#insertBefore()

Insert new node before old node within the container.

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

Returns AtRule.

AtRule#markDirty()

If this node isn't already dirty, marks it and its ancestors as such. This indicates to the LazyResult processor that the Root has been modified by the current plugin and may need to be processed again by other plugins.

AtRule#next()

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

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

Returns ChildNode.

AtRule#nodes

An array containing the layer’s children.

const root = postcss.parse('@layer example { a { color: black } }')
const layer = root.first
layer.nodes.length           //=> 1
layer.nodes[0].selector      //=> 'a'

Can be undefinded if the at-rule has no body.

const root = postcss.parse('@layer a, b, c;')
const layer = root.first
layer.nodes //=> undefined

Type: ChildNode[].

AtRule#parent

It represents parent of the current node.

root.nodes[0].parent === root //=> true

Type: ContainerWithChildren<ChildNode>.

AtRule#positionBy()

Get the position for a word or an index inside the node.

Returns Position.

AtRule#positionInside()

Convert string index to line/column.

Returns Position.

AtRule#prepend()

Inserts new nodes to the start of the container.

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ 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')

Returns AtRule.

AtRule#prev()

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

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

Returns ChildNode.

AtRule#push()

Add child to the end of the node.

rule.push(new Declaration({ prop: 'color', value: 'black' }))

Returns AtRule.

AtRule#rangeBy()

Get the range for a word or start and end index inside the node. The start index is inclusive; the end index is exclusive.

Returns Range.

AtRule#raw()

Returns a 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.

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') //=> ' '

Returns string.

AtRule#raws

It represents unnecessary whitespace and characters present in the css source code.

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

The properties of the raws object are decided by parser, the default parser uses the following properties:

• 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 filters out the comments inside selectors, declaration values and at-rule parameters but it stores the origin content in raws.

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

Type: AtRuleRaws.

AtRule#remove()

It removes the node from its parent and deletes its parent property.

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

Returns AtRule.

AtRule#removeAll()

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

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

Returns AtRule.

AtRule#removeChild()

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

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

Returns AtRule.

AtRule#replaceValues()

Returns AtRule.

AtRule#replaceWith()

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

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

Returns AtRule.

AtRule#root()

Finds the Root instance of the node’s tree.

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

Returns Root.

AtRule#some()

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

const hasPrefix = rule.some(i => i.prop[0] === '-')

Returns boolean.

AtRule#source

It represents information related to origin of a node and is required for generating source maps.

The nodes that are created manually using the public APIs provided by PostCSS will have source undefined and will be absent in the source map.

For this reason, the plugin developer should consider duplicating nodes as the duplicate node will have the same source as the original node by default or assign source to a node created manually.

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

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
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.

AtRule#toJSON()

Fix circular links on JSON.stringify().

Returns object.

AtRule#toString()

It compiles the node to browser readable cascading style sheets string depending on it's type.

new Rule({ selector: 'a' }).toString() //=> "a {}"

Returns string.

AtRule#type

It represents type of a node in an abstract syntax tree.

A type of node helps in identification of a node and perform operation based on it's type.

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

Type: "atrule".

AtRule#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.

root.walk(node => {
  // Traverses all descendant nodes.
})

Returns void | false.

AtRule#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.

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

let first = false
root.walkAtRules('charset', rule => {
  if (!first) {
    first = true
  } else {
    rule.remove()
  }
})

Returns void | false.

AtRule#walkComments()

Returns void | false.

AtRule#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.

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

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

root.walkDecls(/^background/, decl => {
  decl.value = takeFirstColorFromGradient(decl.value)
})

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

Returns void | false.

AtRule#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.

const selectors = []
root.walkRules(rule => {
  selectors.push(rule.selector)
})
console.log(`Your CSS uses ${ selectors.length } selectors`)

Returns void | false.

AtRule#warn()

It is a wrapper for Result#warn, providing convenient way of generating warnings.

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

Returns Warning.

Comment

It represents a class that handles CSS comments

Once (root, { Comment }) {
  const note = new Comment({ text: 'Note: …' })
  root.append(note)
}

Remember that CSS comments inside selectors, at-rule parameters, or declaration values will be stored in the raws properties explained above.

Comment#after()

Insert new node after current node to current node’s parent.

Just alias for node.parent.insertAfter(node, add).

decl.after('color: black')

Returns Comment.

Comment#assign()

It assigns properties to an existing node instance.

decl.assign({ prop: 'word-wrap', value: 'break-word' })

Returns Comment.

Comment#before()

Insert new node before current node to current node’s parent.

Just alias for node.parent.insertBefore(node, add).

decl.before('content: ""')

Returns Comment.

Comment#cleanRaws()

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

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

Comment#clone()

It creates clone of an existing node, which includes all the properties and their values, that includes raws but not type.

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

Returns Comment.

Comment#cloneAfter()

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

Returns Comment.

Comment#cloneBefore()

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

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

Returns Comment.

Comment#error()

It creates an instance of the class CssSyntaxError and parameters passed to this method are assigned to the error instance.

The error instance will have description for the error, original position of the node in the source, showing line and column number.

If any previous map is present, it would be used to get original position of the source.

The Previous Map here is referred to the source map generated by previous compilation, example: Less, Stylus and Sass.

This method returns the error instance instead of throwing it.

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
}

Returns CssSyntaxError_.

Comment#markDirty()

If this node isn't already dirty, marks it and its ancestors as such. This indicates to the LazyResult processor that the Root has been modified by the current plugin and may need to be processed again by other plugins.

Comment#next()

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

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

Returns ChildNode.

Comment#parent

It represents parent of the current node.

root.nodes[0].parent === root //=> true

Type: Container_<ChildNode>.

Comment#positionBy()

Get the position for a word or an index inside the node.

Returns Position.

Comment#positionInside()

Convert string index to line/column.

Returns Position.

Comment#prev()

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

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

Returns ChildNode.

Comment#rangeBy()

Get the range for a word or start and end index inside the node. The start index is inclusive; the end index is exclusive.

Returns Range.

Comment#raw()

Returns a 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.

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') //=> ' '

Returns string.

Comment#raws

It represents unnecessary whitespace and characters present in the css source code.

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

The properties of the raws object are decided by parser, the default parser uses the following properties:

• 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 filters out the comments inside selectors, declaration values and at-rule parameters but it stores the origin content in raws.

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

Type: CommentRaws.

Comment#remove()

It removes the node from its parent and deletes its parent property.

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

Returns Comment.

Comment#replaceWith()

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

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

Returns Comment.

Comment#root()

Finds the Root instance of the node’s tree.

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

Returns Root.

Comment#source

It represents information related to origin of a node and is required for generating source maps.

The nodes that are created manually using the public APIs provided by PostCSS will have source undefined and will be absent in the source map.

For this reason, the plugin developer should consider duplicating nodes as the duplicate node will have the same source as the original node by default or assign source to a node created manually.

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

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
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.

Comment#toJSON()

Fix circular links on JSON.stringify().

Returns object.

Comment#toString()

It compiles the node to browser readable cascading style sheets string depending on it's type.

new Rule({ selector: 'a' }).toString() //=> "a {}"

Returns string.

Comment#type

It represents type of a node in an abstract syntax tree.

A type of node helps in identification of a node and perform operation based on it's type.

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

Type: "comment".

Comment#warn()

It is a wrapper for Result#warn, providing convenient way of generating warnings.

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

Returns Warning.

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.

Container#after()

Insert new node after current node to current node’s parent.

Just alias for node.parent.insertAfter(node, add).

decl.after('color: black')

Returns Container<Child>.

Container#append()

Inserts new nodes to the end of the container.

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ 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')

Returns Container<Child>.

Container#assign()

It assigns properties to an existing node instance.

decl.assign({ prop: 'word-wrap', value: 'break-word' })

Returns Container<Child>.

Container#before()

Insert new node before current node to current node’s parent.

Just alias for node.parent.insertBefore(node, add).

decl.before('content: ""')

Returns Container<Child>.

Container#cleanRaws()

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

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

Container#clone()

It creates clone of an existing node, which includes all the properties and their values, that includes raws but not type.

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

Returns Container<Child>.

Container#cloneAfter()

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

Returns Container<Child>.

Container#cloneBefore()

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

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

Returns Container<Child>.

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.

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

Returns void | false.

Container#error()

It creates an instance of the class CssSyntaxError and parameters passed to this method are assigned to the error instance.

The error instance will have description for the error, original position of the node in the source, showing line and column number.

If any previous map is present, it would be used to get original position of the source.

The Previous Map here is referred to the source map generated by previous compilation, example: Less, Stylus and Sass.

This method returns the error instance instead of throwing it.

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
}

Returns CssSyntaxError_.

Container#every()

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

const noPrefixes = rule.every(i => i.prop[0] !== '-')

Returns boolean.

Container#index()

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

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

Returns number.

Container#insertAfter()

Insert new node after old node within the container.

Returns Container<Child>.

Container#insertBefore()

Insert new node before old node within the container.

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

Returns Container<Child>.

Container#markDirty()

If this node isn't already dirty, marks it and its ancestors as such. This indicates to the LazyResult processor that the Root has been modified by the current plugin and may need to be processed again by other plugins.

Container#next()

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

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

Returns ChildNode.

Container#nodes

An array containing the container’s children.

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

Type: Child[].

Container#parent

It represents parent of the current node.

root.nodes[0].parent === root //=> true

Type: Container_<ChildNode> | Document_.

Container#positionBy()

Get the position for a word or an index inside the node.

Returns Position.

Container#positionInside()

Convert string index to line/column.

Returns Position.

Container#prepend()

Inserts new nodes to the start of the container.

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ 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')

Returns Container<Child>.

Container#prev()

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

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

Returns ChildNode.

Container#push()

Add child to the end of the node.

rule.push(new Declaration({ prop: 'color', value: 'black' }))

Returns Container<Child>.

Container#rangeBy()

Get the range for a word or start and end index inside the node. The start index is inclusive; the end index is exclusive.

Returns Range.

Container#raw()

Returns a 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.

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') //=> ' '

Returns string.

Container#raws

It represents unnecessary whitespace and characters present in the css source code.

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

The properties of the raws object are decided by parser, the default parser uses the following properties:

• 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 filters out the comments inside selectors, declaration values and at-rule parameters but it stores the origin content in raws.

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

Type: any.

Container#remove()

It removes the node from its parent and deletes its parent property.

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

Returns Container<Child>.

Container#removeAll()

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

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

Returns Container<Child>.

Container#removeChild()

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

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

Returns Container<Child>.

Container#replaceValues()

Returns Container<Child>.

Container#replaceWith()

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

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

Returns Container<Child>.

Container#root()

Finds the Root instance of the node’s tree.

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

Returns Root.

Container#some()

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

const hasPrefix = rule.some(i => i.prop[0] === '-')

Returns boolean.

Container#source

It represents information related to origin of a node and is required for generating source maps.

The nodes that are created manually using the public APIs provided by PostCSS will have source undefined and will be absent in the source map.

For this reason, the plugin developer should consider duplicating nodes as the duplicate node will have the same source as the original node by default or assign source to a node created manually.

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

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
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.

Container#toJSON()

Fix circular links on JSON.stringify().

Returns object.

Container#toString()

It compiles the node to browser readable cascading style sheets string depending on it's type.

new Rule({ selector: 'a' }).toString() //=> "a {}"

Returns string.

Container#type

It represents type of a node in an abstract syntax tree.

A type of node helps in identification of a node and perform operation based on it's type.

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

Type: string.

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.

root.walk(node => {
  // Traverses all descendant nodes.
})

Returns void | false.

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.

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

let first = false
root.walkAtRules('charset', rule => {
  if (!first) {
    first = true
  } else {
    rule.remove()
  }
})

Returns void | false.

Container#walkComments()

Returns void | false.

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.

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

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

root.walkDecls(/^background/, decl => {
  decl.value = takeFirstColorFromGradient(decl.value)
})

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

Returns void | false.

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.

const selectors = []
root.walkRules(rule => {
  selectors.push(rule.selector)
})
console.log(`Your CSS uses ${ selectors.length } selectors`)

Returns void | false.

Container#warn()

It is a wrapper for Result#warn, providing convenient way of generating warnings.

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

Returns Warning.

CssSyntaxError

The CSS parser throws this error for broken CSS.

Custom parsers can throw this error for broken custom syntax using the Node#error method.

PostCSS will use the input source map to detect the original error location. If you wrote a Sass file, compiled it to CSS and then parsed it with PostCSS, PostCSS will show the original position in the Sass file.

If you need the position in the PostCSS input (e.g., to debug the previous compiler), use error.input.file.

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

// Catching and checking syntax error
try {
  postcss.parse('a{')
} catch (error) {
  if (error.name === 'CssSyntaxError') {
    error //=> CssSyntaxError
  }
}

CssSyntaxError#captureStackTrace()

Create .stack property on a target object

CssSyntaxError#column

Source column of the error.

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

PostCSS will use the input source map to detect the original location. If you need the position in the PostCSS input, use error.input.column.

Type: number.

CssSyntaxError#endColumn

Source column of the error's end, exclusive. Provided if the error pertains to a range.

error.endColumn       //=> 1
error.input.endColumn //=> 4

PostCSS will use the input source map to detect the original location. If you need the position in the PostCSS input, use error.input.endColumn.

Type: number.

CssSyntaxError#endLine

Source line of the error's end, exclusive. Provided if the error pertains to a range.

error.endLine       //=> 3
error.input.endLine //=> 4

PostCSS will use the input source map to detect the original location. If you need the position in the PostCSS input, use error.input.endLine.

Type: number.

CssSyntaxError#file

Absolute path to the broken file.

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

PostCSS will use the input source map to detect the original location. If you need the position in the PostCSS input, use error.input.file.

Type: string.

CssSyntaxError#input

Input object with PostCSS internal information about input file. If input has source map from previous tool, PostCSS will use origin (for example, Sass) source. You can use this object to get PostCSS input source.

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

Type: FilePosition.

CssSyntaxError#line

Source line of the error.

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

PostCSS will use the input source map to detect the original location. If you need the position in the PostCSS input, use error.input.line.

Type: number.

CssSyntaxError#message

Full error text in the GNU error format with plugin, file, line and column.

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

Type: string.

CssSyntaxError#name

Always equal to 'CssSyntaxError'. You should always check error type by error.name === 'CssSyntaxError' instead of error instanceof CssSyntaxError, because npm could have several PostCSS versions.

if (error.name === 'CssSyntaxError') {
  error //=> CssSyntaxError
}

Type: "CssSyntaxError".

CssSyntaxError#plugin

Plugin name, if error came from plugin.

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

Type: string.

CssSyntaxError#prepareStackTrace

Type: Function.

CssSyntaxError#reason

Error message.

error.message //=> 'Unclosed block'

Type: string.

CssSyntaxError#showSourceCode()

Returns a few lines of CSS source that caused the error.

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

error.showSourceCode() //=> "  4 | }
                       //      5 | a {
                       //    > 6 |   bad
                       //        |   ^
                       //      7 | }
                       //      8 | b {"

Returns string.

CssSyntaxError#source

Source code of the broken file.

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

Type: string.

CssSyntaxError#stack

Type: string.

CssSyntaxError#stackTraceLimit

Type: number.

CssSyntaxError#toString()

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

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

Returns string.

Declaration

It represents a class that handles CSS declarations

Once (root, { Declaration }) {
  const color = new Declaration({ prop: 'color', value: 'black' })
  root.append(color)
}

const root = postcss.parse('a { color: black }')
const decl = root.first?.first

decl.type       //=> 'decl'
decl.toString() //=> ' color: black'

Declaration#after()

Insert new node after current node to current node’s parent.

Just alias for node.parent.insertAfter(node, add).

decl.after('color: black')

Returns Declaration.

Declaration#assign()

It assigns properties to an existing node instance.

decl.assign({ prop: 'word-wrap', value: 'break-word' })

Returns Declaration.

Declaration#before()

Insert new node before current node to current node’s parent.

Just alias for node.parent.insertBefore(node, add).

decl.before('content: ""')

Returns Declaration.

Declaration#cleanRaws()

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

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

Declaration#clone()

It creates clone of an existing node, which includes all the properties and their values, that includes raws but not type.

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

Returns Declaration.

Declaration#cloneAfter()

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

Returns Declaration.

Declaration#cloneBefore()

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

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

Returns Declaration.

Declaration#error()

It creates an instance of the class CssSyntaxError and parameters passed to this method are assigned to the error instance.

The error instance will have description for the error, original position of the node in the source, showing line and column number.

If any previous map is present, it would be used to get original position of the source.

The Previous Map here is referred to the source map generated by previous compilation, example: Less, Stylus and Sass.

This method returns the error instance instead of throwing it.

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
}

Returns CssSyntaxError_.

Declaration#markDirty()

If this node isn't already dirty, marks it and its ancestors as such. This indicates to the LazyResult processor that the Root has been modified by the current plugin and may need to be processed again by other plugins.

Declaration#next()

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

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

Returns ChildNode.

Declaration#parent

It represents parent of the current node.

root.nodes[0].parent === root //=> true

Type: ContainerWithChildren<ChildNode>.

Declaration#positionBy()

Get the position for a word or an index inside the node.

Returns Position.

Declaration#positionInside()

Convert string index to line/column.

Returns Position.

Declaration#prev()

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

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

Returns ChildNode.

Declaration#rangeBy()

Get the range for a word or start and end index inside the node. The start index is inclusive; the end index is exclusive.

Returns Range.

Declaration#raw()

Returns a 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.

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') //=> ' '

Returns string.

Declaration#raws

It represents unnecessary whitespace and characters present in the css source code.

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

The properties of the raws object are decided by parser, the default parser uses the following properties:

• 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 filters out the comments inside selectors, declaration values and at-rule parameters but it stores the origin content in raws.

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

Type: DeclarationRaws.

Declaration#remove()

It removes the node from its parent and deletes its parent property.

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

Returns Declaration.

Declaration#replaceWith()

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

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

Returns Declaration.

Declaration#root()

Finds the Root instance of the node’s tree.

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

Returns Root.

Declaration#source

It represents information related to origin of a node and is required for generating source maps.

The nodes that are created manually using the public APIs provided by PostCSS will have source undefined and will be absent in the source map.

For this reason, the plugin developer should consider duplicating nodes as the duplicate node will have the same source as the original node by default or assign source to a node created manually.

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

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
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.

Declaration#toJSON()

Fix circular links on JSON.stringify().

Returns object.

Declaration#toString()

It compiles the node to browser readable cascading style sheets string depending on it's type.

new Rule({ selector: 'a' }).toString() //=> "a {}"

Returns string.

Declaration#type

It represents type of a node in an abstract syntax tree.

A type of node helps in identification of a node and perform operation based on it's type.

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

Type: "decl".

Declaration#warn()

It is a wrapper for Result#warn, providing convenient way of generating warnings.

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

Returns Warning.

Document

Represents a file and contains all its parsed nodes.

Experimental: some aspects of this node could change within minor or patch version releases.

const document = htmlParser(
  '<html><style>a{color:black}</style><style>b{z-index:2}</style>'
)
document.type         //=> 'document'
document.nodes.length //=> 2

Document#after()

Insert new node after current node to current node’s parent.

Just alias for node.parent.insertAfter(node, add).

decl.after('color: black')

Returns Document.

Document#append()

Inserts new nodes to the end of the container.

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ 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')

Returns Document.

Document#assign()

It assigns properties to an existing node instance.

decl.assign({ prop: 'word-wrap', value: 'break-word' })

Returns Document.

Document#before()

Insert new node before current node to current node’s parent.

Just alias for node.parent.insertBefore(node, add).

decl.before('content: ""')

Returns Document.

Document#cleanRaws()

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

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

Document#clone()

It creates clone of an existing node, which includes all the properties and their values, that includes raws but not type.

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

Returns Document.

Document#cloneAfter()

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

Returns Document.

Document#cloneBefore()

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

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

Returns Document.

Document#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.

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

Returns void | false.

Document#error()

It creates an instance of the class CssSyntaxError and parameters passed to this method are assigned to the error instance.

The error instance will have description for the error, original position of the node in the source, showing line and column number.

If any previous map is present, it would be used to get original position of the source.

The Previous Map here is referred to the source map generated by previous compilation, example: Less, Stylus and Sass.

This method returns the error instance instead of throwing it.

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
}

Returns CssSyntaxError_.

Document#every()

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

const noPrefixes = rule.every(i => i.prop[0] !== '-')

Returns boolean.

Document#index()

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

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

Returns number.

Document#insertAfter()

Insert new node after old node within the container.

Returns Document.

Document#insertBefore()

Insert new node before old node within the container.

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

Returns Document.

Document#markDirty()

If this node isn't already dirty, marks it and its ancestors as such. This indicates to the LazyResult processor that the Root has been modified by the current plugin and may need to be processed again by other plugins.

Document#next()

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

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

Returns ChildNode.

Document#nodes

An array containing the container’s children.

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

Type: Root[].

Document#parent

It represents parent of the current node.

root.nodes[0].parent === root //=> true

Type: undefined.

Document#positionBy()

Get the position for a word or an index inside the node.

Returns Position.

Document#positionInside()

Convert string index to line/column.

Returns Position.

Document#prepend()

Inserts new nodes to the start of the container.

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ 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')

Returns Document.

Document#prev()

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

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

Returns ChildNode.

Document#push()

Add child to the end of the node.

rule.push(new Declaration({ prop: 'color', value: 'black' }))

Returns Document.

Document#rangeBy()

Get the range for a word or start and end index inside the node. The start index is inclusive; the end index is exclusive.

Returns Range.

Document#raw()

Returns a 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.

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') //=> ' '

Returns string.

Document#raws

It represents unnecessary whitespace and characters present in the css source code.

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

The properties of the raws object are decided by parser, the default parser uses the following properties:

• 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 filters out the comments inside selectors, declaration values and at-rule parameters but it stores the origin content in raws.

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

Type: any.

Document#remove()

It removes the node from its parent and deletes its parent property.

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

Returns Document.

Document#removeAll()

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

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

Returns Document.

Document#removeChild()

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

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

Returns Document.

Document#replaceValues()

Returns Document.

Document#replaceWith()

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

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

Returns Document.

Document#root()

Finds the Root instance of the node’s tree.

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

Returns Root.

Document#some()

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

const hasPrefix = rule.some(i => i.prop[0] === '-')

Returns boolean.

Document#source

It represents information related to origin of a node and is required for generating source maps.

The nodes that are created manually using the public APIs provided by PostCSS will have source undefined and will be absent in the source map.

For this reason, the plugin developer should consider duplicating nodes as the duplicate node will have the same source as the original node by default or assign source to a node created manually.

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

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
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.

Document#toJSON()

Fix circular links on JSON.stringify().

Returns object.

Document#toResult()

Returns a Result instance representing the document’s CSS roots.

const root1 = postcss.parse(css1, { from: 'a.css' })
const root2 = postcss.parse(css2, { from: 'b.css' })
const document = postcss.document()
document.append(root1)
document.append(root2)
const result = document.toResult({ to: 'all.css', map: true })

Returns Result<Document_ | Root>.

Document#toString()

It compiles the node to browser readable cascading style sheets string depending on it's type.

new Rule({ selector: 'a' }).toString() //=> "a {}"

Returns string.

Document#type

It represents type of a node in an abstract syntax tree.

A type of node helps in identification of a node and perform operation based on it's type.

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

Type: "document".

Document#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.

root.walk(node => {
  // Traverses all descendant nodes.
})

Returns void | false.

Document#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.

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

let first = false
root.walkAtRules('charset', rule => {
  if (!first) {
    first = true
  } else {
    rule.remove()
  }
})

Returns void | false.

Document#walkComments()

Returns void | false.

Document#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.

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

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

root.walkDecls(/^background/, decl => {
  decl.value = takeFirstColorFromGradient(decl.value)
})

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

Returns void | false.

Document#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.

const selectors = []
root.walkRules(rule => {
  selectors.push(rule.selector)
})
console.log(`Your CSS uses ${ selectors.length } selectors`)

Returns void | false.

Document#warn()

It is a wrapper for Result#warn, providing convenient way of generating warnings.

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

Returns Warning.

Input

Represents the source CSS.

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

Input#css

Input CSS source.

const input = postcss.parse('a{}', { from: file }).input
input.css //=> "a{}"

Type: string.

Input#error()

Returns CssSyntaxError_.

Input#file

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

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

Type: string.

Input#fromOffset()

Converts source offset to line and column.

Returns Object.

Input#hasBOM

The flag to indicate whether or not the source code has Unicode BOM.

Type: boolean.

Input#id

The unique ID of the CSS source. It will be created if from option is not provided (because PostCSS does not know the file path).

const root = postcss.parse(css)
root.source.input.file //=> undefined
root.source.input.id   //=> "<input css 8LZeVF>"

Type: string.

Input#map

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

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

Type: PreviousMap_.

Input#origin()

Reads the input source map and returns a symbol position in the input source (e.g., in a Sass file that was compiled to CSS before being passed to PostCSS). Optionally takes an end position, exclusive.

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

Returns false | FilePosition.

Input#toJSON()

Converts this to a JSON-friendly object representation.

Returns object.

LazyResult

A Promise proxy for the result of PostCSS transformations.

A LazyResult instance is returned by Processor#process.

const lazy = postcss([autoprefixer]).process(css)

LazyResult#async()

Run plugin in async way and return Result.

Returns Promise<Result<RootNode>>.

LazyResult#catch

Type: Function.

LazyResult#finally

Type: Function.

LazyResult#sync()

Run plugin in sync way and return Result.

Returns Result<RootNode>.

LazyResult#then

Type: Function.

LazyResult#toString()

Alias for the LazyResult#css property.

lazy + '' === lazy.css

Returns string.

LazyResult#warnings()

Processes input CSS through synchronous plugins and calls Result#warnings.

Returns Warning[].

NoWorkResult

A Promise proxy for the result of PostCSS transformations. This lazy result instance doesn't parse css unless NoWorkResult#root or Result#root are accessed. See the example below for details. A NoWork instance is returned by Processor#process ONLY when no plugins defined.

const noWorkResult = postcss().process(css) // No plugins are defined.
                                            // CSS is not parsed
let root = noWorkResult.root // now css is parsed because we accessed the root

NoWorkResult#async()

Run plugin in async way and return Result.

Returns Promise<Result<Root>>.

NoWorkResult#catch

Type: Function.

NoWorkResult#finally

Type: Function.

NoWorkResult#sync()

Run plugin in sync way and return Result.

Returns Result<Root>.

NoWorkResult#then

Type: Function.

NoWorkResult#toString()

Alias for the LazyResult#css property.

lazy + '' === lazy.css

Returns string.

NoWorkResult#warnings()

Processes input CSS through synchronous plugins and calls Result#warnings.

Returns Warning[].

Node

Node#after()

Insert new node after current node to current node’s parent.

Just alias for node.parent.insertAfter(node, add).

decl.after('color: black')

Returns Node.

Node#assign()

It assigns properties to an existing node instance.

decl.assign({ prop: 'word-wrap', value: 'break-word' })

Returns Node.

Node#before()

Insert new node before current node to current node’s parent.

Just alias for node.parent.insertBefore(node, add).

decl.before('content: ""')

Returns Node.

Node#cleanRaws()

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

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

Node#clone()

It creates clone of an existing node, which includes all the properties and their values, that includes raws but not type.

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

Returns Node.

Node#cloneAfter()

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

Returns Node.

Node#cloneBefore()

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

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

Returns Node.

Node#error()

It creates an instance of the class CssSyntaxError and parameters passed to this method are assigned to the error instance.

The error instance will have description for the error, original position of the node in the source, showing line and column number.

If any previous map is present, it would be used to get original position of the source.

The Previous Map here is referred to the source map generated by previous compilation, example: Less, Stylus and Sass.

This method returns the error instance instead of throwing it.

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
}

Returns CssSyntaxError_.

Node#markDirty()

If this node isn't already dirty, marks it and its ancestors as such. This indicates to the LazyResult processor that the Root has been modified by the current plugin and may need to be processed again by other plugins.

Node#next()

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

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

Returns ChildNode.

Node#parent

It represents parent of the current node.

root.nodes[0].parent === root //=> true

Type: Container_<ChildNode> | Document_.

Node#positionBy()

Get the position for a word or an index inside the node.

Returns Position.

Node#positionInside()

Convert string index to line/column.

Returns Position.

Node#prev()

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

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

Returns ChildNode.

Node#rangeBy()

Get the range for a word or start and end index inside the node. The start index is inclusive; the end index is exclusive.

Returns Range.

Node#raw()

Returns a 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.

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') //=> ' '

Returns string.

Node#raws

It represents unnecessary whitespace and characters present in the css source code.

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

The properties of the raws object are decided by parser, the default parser uses the following properties:

• 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 filters out the comments inside selectors, declaration values and at-rule parameters but it stores the origin content in raws.

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

Type: any.

Node#remove()

It removes the node from its parent and deletes its parent property.

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

Returns Node.

Node#replaceWith()

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

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

Returns Node.

Node#root()

Finds the Root instance of the node’s tree.

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

Returns Root.

Node#source

It represents information related to origin of a node and is required for generating source maps.

The nodes that are created manually using the public APIs provided by PostCSS will have source undefined and will be absent in the source map.

For this reason, the plugin developer should consider duplicating nodes as the duplicate node will have the same source as the original node by default or assign source to a node created manually.

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

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
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.

Node#toJSON()

Fix circular links on JSON.stringify().

Returns object.

Node#toString()

It compiles the node to browser readable cascading style sheets string depending on it's type.

new Rule({ selector: 'a' }).toString() //=> "a {}"

Returns string.

Node#type

It represents type of a node in an abstract syntax tree.

A type of node helps in identification of a node and perform operation based on it's type.

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

Type: string.

Node#warn()

It is a wrapper for Result#warn, providing convenient way of generating warnings.

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

Returns Warning.

PreviousMap

Source map information from input CSS. For example, source map after Sass compiler.

This class will automatically find source map in input CSS or in file system near input file (according from option).

const root = parse(css, { from: 'a.sass.css' })
root.input.map //=> PreviousMap

PreviousMap#annotation

sourceMappingURL content.

Type: string.

PreviousMap#consumer()

Create a instance of SourceMapGenerator class from the source-map library to work with source map information.

It is lazy method, so it will create object only on first call and then it will use cache.

Returns SourceMapConsumer.

PreviousMap#file

The CSS source identifier. Contains Input#file if the user set the from option, or Input#id if they did not.

Type: string.

PreviousMap#inline

Was source map inlined by data-uri to input CSS.

Type: boolean.

PreviousMap#mapFile

Path to source map file.

Type: string.

PreviousMap#root

The directory with source map file, if source map is in separated file.

Type: string.

PreviousMap#text

Source map file content.

Type: string.

PreviousMap#withContent()

Does source map contains sourcesContent with input source text.

Returns boolean.

Processor

Contains plugins to process CSS. Create one Processor instance, initialize its plugins, and then use that instance on numerous CSS files.

const processor = postcss([autoprefixer, postcssNested])
processor.process(css1).then(result => console.log(result.css))
processor.process(css2).then(result => console.log(result.css))

Processor#plugins

Plugins added to this processor.

const processor = postcss([autoprefixer, postcssNested])
processor.plugins.length //=> 2

Type: (Plugin | TransformCallback | Transformer)[].

Processor#process()

Parses source CSS and returns a LazyResult Promise proxy. Because some plugins can be asynchronous it doesn’t make any transformations. Transformations will be applied in the LazyResult methods.

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

Returns NoWorkResult_ | LazyResult_<Document_ | Root>.

Processor#use()

Adds a plugin to be used as a CSS processor.

PostCSS plugin can be in 4 formats:

• A plugin in Plugin format.
• A plugin creator function with pluginCreator.postcss = true. PostCSS will call this function without argument to get plugin.
• A function. PostCSS will pass the function a Root as the first argument and current Result instance as the second.
• Another Processor instance. PostCSS will copy plugins from that instance into this one.

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

Asynchronous plugins should return a Promise instance.

const processor = postcss()
  .use(autoprefixer)
  .use(postcssNested)

Returns Processor.

Processor#version

Current PostCSS version.

if (result.processor.version.split('.')[0] !== '6') {
  throw new Error('This plugin works only with PostCSS 6')
}

Type: string.

Result

Provides the result of the PostCSS transformations.

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

postcss([autoprefixer]).process(css).then(result => {
 console.log(result.css)
})

const result2 = postcss.parse(css).toResult()

Result#css

A CSS string representing of Result#root.

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

Type: string.

Result#lastPlugin

Last runned PostCSS plugin.

Type: Plugin | TransformCallback.

Result#map

An instance of SourceMapGenerator class from the source-map library, representing changes to the Result#root instance.

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

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

Type: SourceMap.

Result#messages

Contains messages from plugins (e.g., warnings or custom messages). Each message should have type and plugin properties.

AtRule: {
  import: (atRule, { result }) {
    const importedFile = parseImport(atRule)
    result.messages.push({
      type: 'dependency',
      plugin: 'postcss-import',
      file: importedFile,
      parent: result.opts.from
    })
  }
}

Type: Message[].

Result#opts

Options from the Processor#process or Root#toResult call that produced this Result instance.]

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

Type: ResultOptions.

Result#processor

The Processor instance used for this transformation.

for (const plugin of result.processor.plugins) {
  if (plugin.postcssPlugin === 'postcss-bad') {
    throw 'postcss-good is incompatible with postcss-bad'
  }
})

Type: Processor.

Result#root

Root node after all transformations.

root.toResult().root === root

Type: RootNode.

Result#toString()

Returns for Result#css content.

result + '' === result.css

Returns string.

Result#warn()

Creates an instance of Warning and adds it to Result#messages.

if (decl.important) {
  result.warn('Avoid !important', { node: decl, word: '!important' })
}

Returns Warning.

Result#warnings()

Returns warnings from plugins. Filters Warning instances from Result#messages.

result.warnings().forEach(warn => {
  console.warn(warn.toString())
})

Returns Warning[].

Root

Represents a CSS file and contains all its parsed nodes.

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

Root#after()

Insert new node after current node to current node’s parent.

Just alias for node.parent.insertAfter(node, add).

decl.after('color: black')

Returns Root.

Root#append()

Inserts new nodes to the end of the container.

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ 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')

Returns Root.

Root#assign()

It assigns properties to an existing node instance.

decl.assign({ prop: 'word-wrap', value: 'break-word' })

Returns Root.

Root#before()

Insert new node before current node to current node’s parent.

Just alias for node.parent.insertBefore(node, add).

decl.before('content: ""')

Returns Root.

Root#cleanRaws()

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

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

Root#clone()

It creates clone of an existing node, which includes all the properties and their values, that includes raws but not type.

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

Returns Root.

Root#cloneAfter()

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

Returns Root.

Root#cloneBefore()

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

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

Returns Root.

Root#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.

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

Returns void | false.

Root#error()

It creates an instance of the class CssSyntaxError and parameters passed to this method are assigned to the error instance.

The error instance will have description for the error, original position of the node in the source, showing line and column number.

If any previous map is present, it would be used to get original position of the source.

The Previous Map here is referred to the source map generated by previous compilation, example: Less, Stylus and Sass.

This method returns the error instance instead of throwing it.

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
}

Returns CssSyntaxError_.

Root#every()

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

const noPrefixes = rule.every(i => i.prop[0] !== '-')

Returns boolean.

Root#index()

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

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

Returns number.

Root#insertAfter()

Insert new node after old node within the container.

Returns Root.

Root#insertBefore()

Insert new node before old node within the container.

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

Returns Root.

Root#markDirty()

If this node isn't already dirty, marks it and its ancestors as such. This indicates to the LazyResult processor that the Root has been modified by the current plugin and may need to be processed again by other plugins.

Root#next()

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

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

Returns ChildNode.

Root#nodes

An array containing the container’s children.

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

Type: ChildNode[].

Root#parent

It represents parent of the current node.

root.nodes[0].parent === root //=> true

Type: Document_.

Root#positionBy()

Get the position for a word or an index inside the node.

Returns Position.

Root#positionInside()

Convert string index to line/column.

Returns Position.

Root#prepend()

Inserts new nodes to the start of the container.

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ 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')

Returns Root.

Root#prev()

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

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

Returns ChildNode.

Root#push()

Add child to the end of the node.

rule.push(new Declaration({ prop: 'color', value: 'black' }))

Returns Root.

Root#rangeBy()

Get the range for a word or start and end index inside the node. The start index is inclusive; the end index is exclusive.

Returns Range.

Root#raw()

Returns a 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.

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') //=> ' '

Returns string.

Root#raws

It represents unnecessary whitespace and characters present in the css source code.

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

The properties of the raws object are decided by parser, the default parser uses the following properties:

• 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 filters out the comments inside selectors, declaration values and at-rule parameters but it stores the origin content in raws.

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

Type: RootRaws.

Root#remove()

It removes the node from its parent and deletes its parent property.

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

Returns Root.

Root#removeAll()

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

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

Returns Root.

Root#removeChild()

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

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

Returns Root.

Root#replaceValues()

Returns Root.

Root#replaceWith()

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

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

Returns Root.

Root#root()

Finds the Root instance of the node’s tree.

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

Returns Root.

Root#some()

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

const hasPrefix = rule.some(i => i.prop[0] === '-')

Returns boolean.

Root#source

It represents information related to origin of a node and is required for generating source maps.

The nodes that are created manually using the public APIs provided by PostCSS will have source undefined and will be absent in the source map.

For this reason, the plugin developer should consider duplicating nodes as the duplicate node will have the same source as the original node by default or assign source to a node created manually.

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

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
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.

Root#toJSON()

Fix circular links on JSON.stringify().

Returns object.

Root#toResult()

Returns a Result instance representing the root’s CSS.

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

Returns Result<Document_ | Root>.

Root#toString()

It compiles the node to browser readable cascading style sheets string depending on it's type.

new Rule({ selector: 'a' }).toString() //=> "a {}"

Returns string.

Root#type

It represents type of a node in an abstract syntax tree.

A type of node helps in identification of a node and perform operation based on it's type.

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

Type: "root".

Root#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.

root.walk(node => {
  // Traverses all descendant nodes.
})