append (children)

Inserts new nodes to the end of the container.

Returns

Examples

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

each (callback)

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.

Returns

Examples

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

every (condition)

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

Returns

Examples

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

first ()

The container’s first child.

Type: Node

Examples

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

index (child)

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

Returns

Examples

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

insertAfter (exist, add)

Insert new node after old node within the container.

Returns

insertBefore (exist, add)

Insert new node before old node within the container.

Returns

Examples

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

last ()

The container’s last child.

Type: Node

Examples

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

prepend (children)

Inserts new nodes to the start of the container.

Returns

Examples

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

removeAll ()

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

Returns

Examples

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

removeChild (child)

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

Returns

Examples

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

replaceValues (pattern, opts, callback)

Passes all declaration values within the container that match pattern through callback, replacing those values with the returned result of callback.

This method is useful if you are using a custom unit or function and need to iterate through all values.

Returns

Examples

root.replaceValues(/\d+rem/, { fast: 'rem' }, string => {
  return 15 * parseInt(string) + 'px'
})

some (condition)

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

Returns

Examples

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

walk (callback)

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.

Returns

Examples

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

walkAtRules (name?, callback)

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.

Returns

Examples

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

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

walkComments (callback)

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.

Returns

Examples

root.walkComments(comment => {
  comment.remove()
})

walkDecls (prop?, callback)

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.

Returns

Examples

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

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

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

walkRules (selector?, callback)

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.

Returns

Examples

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

after (add)

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

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

Returns

Examples

decl.after('color: black')

before (add)

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

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

Returns

Examples

decl.before('content: ""')

cleanRaws (keepBetween?)

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

Returns

Examples

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

clone (overrides = {})

Returns an exact clone of the node.

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

Returns

Examples

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

cloneAfter (overrides = {})

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

Returns

cloneBefore (overrides = {})

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

Returns

Examples

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

error (message, opts = {})

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

If present, an input source map will be used to get the original position of the source, even from a previous compilation step (e.g., from Sass compilation).

This method produces very useful error messages.

Returns

Examples

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
}

next ()

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

Returns

Examples

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

prev ()

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

Returns

Examples

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

raw (prop, defaultType?)

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.

Returns

Examples

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

remove ()

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

Returns

Examples

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

replaceWith (nodes)

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

Returns

Examples

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

root ()

Finds the Root instance of the node’s tree.

Returns

Examples

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

toString (stringifier = stringify)

Returns a CSS string representing the node.

Returns

Examples

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

warn (result, text, opts?)

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

Returns

Examples

const plugin = postcss.plugin('postcss-deprecated', () => {
  return (root, result) => {
    root.walkDecls('bad', decl => {
      decl.warn(result, 'Deprecated property bad')
    })
  }
})

after (add)

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

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

Returns

Examples

decl.after('color: black')

append (children)

Inserts new nodes to the end of the container.

Returns

Examples

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

before (add)

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

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

Returns

Examples

decl.before('content: ""')

cleanRaws (keepBetween?)

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

Returns

Examples

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

clone (overrides = {})

Returns an exact clone of the node.

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

Returns

Examples

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

cloneAfter (overrides = {})

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

Returns

cloneBefore (overrides = {})

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

Returns

Examples

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

each (callback)

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.

Returns

Examples

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

error (message, opts = {})

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

If present, an input source map will be used to get the original position of the source, even from a previous compilation step (e.g., from Sass compilation).

This method produces very useful error messages.

Returns

Examples

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
}

every (condition)

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

Returns

Examples

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

first ()

The container’s first child.

Type: Node

Examples

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

index (child)

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

Returns

Examples

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

insertAfter (exist, add)

Insert new node after old node within the container.

Returns

insertBefore (exist, add)

Insert new node before old node within the container.

Returns

Examples

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

last ()

The container’s last child.

Type: Node

Examples

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

next ()

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

Returns

Examples

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

prepend (children)

Inserts new nodes to the start of the container.

Returns

Examples

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

prev ()

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

Returns

Examples

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

raw (prop, defaultType?)

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.

Returns

Examples

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

remove ()

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

Returns

Examples

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

removeAll ()

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

Returns

Examples

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

removeChild (child)

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

Returns

Examples

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

replaceValues (pattern, opts, callback)

Passes all declaration values within the container that match pattern through callback, replacing those values with the returned result of callback.

This method is useful if you are using a custom unit or function and need to iterate through all values.

Returns

Examples

root.replaceValues(/\d+rem/, { fast: 'rem' }, string => {
  return 15 * parseInt(string) + 'px'
})

replaceWith (nodes)

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

Returns

Examples

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

root ()

Finds the Root instance of the node’s tree.

Returns

Examples

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

some (condition)

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

Returns

Examples

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

toString (stringifier = stringify)

Returns a CSS string representing the node.

Returns

Examples

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

walk (callback)

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.

Returns

Examples

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

walkAtRules (name?, callback)

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.

Returns

Examples

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

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

walkComments (callback)

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.

Returns

Examples

root.walkComments(comment => {
  comment.remove()
})

walkDecls (prop?, callback)

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.

Returns

Examples

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

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

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

walkRules (selector?, callback)

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.

Returns

Examples

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

warn (result, text, opts?)

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

Returns

Examples

const plugin = postcss.plugin('postcss-deprecated', () => {
  return (root, result) => {
    root.walkDecls('bad', decl => {
      decl.warn(result, 'Deprecated property bad')
    })
  }
})

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.

Type: string

Examples

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

reason ()

Error message.

Type: string

Examples

error.message //=> 'Unclosed block'

file ()

Absolute path to the broken file.

Type: string

Examples

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

source ()

Source code of the broken file.

Type: string

Examples

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

plugin ()

Plugin name, if error came from plugin.

Type: string

Examples

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

line ()

Source line of the error.

Type: number

Examples

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

column ()

Source column of the error.

Type: number

Examples

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

message ()

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

Type: string

Examples

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

showSourceCode (color?)

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.

Returns

Examples

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

toString ()

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

Returns

Examples

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

after (add)

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

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

Returns

Examples

decl.after('color: black')

before (add)

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

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

Returns

Examples

decl.before('content: ""')

cleanRaws (keepBetween?)

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

Returns

Examples

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

clone (overrides = {})

Returns an exact clone of the node.

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

Returns

Examples

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

cloneAfter (overrides = {})

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

Returns

cloneBefore (overrides = {})

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

Returns

Examples

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

error (message, opts = {})

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

If present, an input source map will be used to get the original position of the source, even from a previous compilation step (e.g., from Sass compilation).

This method produces very useful error messages.

Returns

Examples

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
}

next ()

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

Returns

Examples

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

prev ()

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

Returns

Examples

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

raw (prop, defaultType?)

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.

Returns

Examples

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

remove ()

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

Returns

Examples

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

replaceWith (nodes)

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

Returns

Examples

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

root ()

Finds the Root instance of the node’s tree.

Returns

Examples

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

toString (stringifier = stringify)

Returns a CSS string representing the node.

Returns

Examples

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

warn (result, text, opts?)

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

Returns

Examples

const plugin = postcss.plugin('postcss-deprecated', () => {
  return (root, result) => {
    root.walkDecls('bad', decl => {
      decl.warn(result, 'Deprecated property bad')
    })
  }
})

css ()

Input CSS source

Type: string

Examples

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

file ()

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

Type: string

Examples

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

map ()

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

Type: PreviousMap

Examples

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

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

Type: string

Examples

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

origin (line, column)

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

Returns

Examples

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

from ()

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

Type: string

Examples

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

const root = postcss.parse(css)
root.source.input.from //=> "<input css 1>"

processor ()

Returns a Processor instance, which will be used for CSS transformations.

Type: Processor

opts ()

Options from the Processor#process call.

Type: processOptions

css ()

Processes input CSS through synchronous plugins, converts Root to a CSS string and returns Result#css.

This property will only work with synchronous plugins. If the processor contains any asynchronous plugins it will throw an error. This is why this method is only for debug purpose, you should always use LazyResult#then.

Type: string

content ()

An alias for the css property. Use it with syntaxes that generate non-CSS output.

This property will only work with synchronous plugins. If the processor contains any asynchronous plugins it will throw an error. This is why this method is only for debug purpose, you should always use LazyResult#then.

Type: string

map ()

Processes input CSS through synchronous plugins and returns Result#map.

This property will only work with synchronous plugins. If the processor contains any asynchronous plugins it will throw an error. This is why this method is only for debug purpose, you should always use LazyResult#then.

Type: SourceMapGenerator

root ()

Processes input CSS through synchronous plugins and returns Result#root.

This property will only work with synchronous plugins. If the processor contains any asynchronous plugins it will throw an error.

This is why this method is only for debug purpose, you should always use LazyResult#then.

Type: Root

messages ()

Processes input CSS through synchronous plugins and returns Result#messages.

This property will only work with synchronous plugins. If the processor contains any asynchronous plugins it will throw an error.

This is why this method is only for debug purpose, you should always use LazyResult#then.

Type: Array<Message>

warnings ()

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

Returns

toString ()

Alias for the LazyResult#css property.

Returns

Examples

lazy + '' === lazy.css

then (onFulfilled, onRejected)

Processes input CSS through synchronous and asynchronous plugins and calls onFulfilled with a Result instance. If a plugin throws an error, the onRejected callback will be executed.

It implements standard Promise API.

Returns

Examples

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

catch (onRejected)

Processes input CSS through synchronous and asynchronous plugins and calls onRejected for each error thrown in any plugin.

It implements standard Promise API.

Returns

Examples

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

finally (onFinally)

Processes input CSS through synchronous and asynchronous plugins and calls onFinally on any error or when all plugins will finish work.

It implements standard Promise API.

Returns

Examples

postcss([autoprefixer]).process(css).finally(() => {
  console.log('processing ended')
})

error (message, opts = {})

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

If present, an input source map will be used to get the original position of the source, even from a previous compilation step (e.g., from Sass compilation).

This method produces very useful error messages.

Returns

Examples

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
}

warn (result, text, opts?)

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

Returns

Examples

const plugin = postcss.plugin('postcss-deprecated', () => {
  return (root, result) => {
    root.walkDecls('bad', decl => {
      decl.warn(result, 'Deprecated property bad')
    })
  }
})

remove ()

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

Returns

Examples

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

toString (stringifier = stringify)

Returns a CSS string representing the node.

Returns

Examples

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

clone (overrides = {})

Returns an exact clone of the node.

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

Returns

Examples

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

cloneBefore (overrides = {})

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

Returns

Examples

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

cloneAfter (overrides = {})

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

Returns

replaceWith (nodes)

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

Returns

Examples

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

next ()

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

Returns

Examples

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

prev ()

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

Returns

Examples

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

before (add)

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

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

Returns

Examples

decl.before('content: ""')

after (add)

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

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

Returns

Examples

decl.after('color: black')

raw (prop, defaultType?)

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.

Returns

Examples

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

root ()

Finds the Root instance of the node’s tree.

Returns

Examples

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

cleanRaws (keepBetween?)

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

Returns

Examples

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

inline ()

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

Type: boolean

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

withContent ()

Does source map contains sourcesContent with input source text.

Returns

version ()

Current PostCSS version.

Type: string

Examples

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

plugins ()

Plugins added to this processor.

Type: Array<pluginFunction>

Examples

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

use (plugin)

Adds a plugin to be used as a CSS processor.

PostCSS plugin can be in 4 formats:

• A plugin created by postcss.plugin method.
• A function. PostCSS will pass the function a @{link Root} as the first argument and current Result instance as the second.
• An object with a postcss method. PostCSS will use that method as described in #2.
• Another Processor instance. PostCSS will copy plugins from that instance 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.

Returns

Examples

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

process (css, opts = {})

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.

Returns

Examples

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

processor ()

The Processor instance used for this transformation.

Type: Processor

Examples

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

messages ()

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

Type: Array<Message>

Examples

postcss.plugin('postcss-min-browser', () => {
  return (root, result) => {
    const browsers = detectMinBrowsersByCanIUse(root)
    result.messages.push({
      type: 'min-browser',
      plugin: 'postcss-min-browser',
      browsers
    })
  }
})

root ()

Root node after all transformations.

Type: Root

Examples

root.toResult().root === root

opts ()

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

Type: processOptions

Examples

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

css ()

A CSS string representing of Result#root.

Type: string

Examples

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

map ()

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

Type: SourceMapGenerator

Examples

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

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

toString ()

Returns for @{link Result#css} content.

Returns

Examples

result + '' === result.css

warn (text, opts = {})

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

Returns

warnings ()

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

Returns

Examples

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

content ()

An alias for the Result#css property. Use it with syntaxes that generate non-CSS output.

Type: string

Examples

result.css === result.content

registerLazyResult (dependant)

append (children)

Inserts new nodes to the end of the container.

Returns

Examples

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

each (callback)

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.

Returns

Examples

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

every (condition)

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

Returns

Examples

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

first ()

The container’s first child.

Type: Node

Examples

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

index (child)

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

Returns

Examples

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

insertAfter (exist, add)

Insert new node after old node within the container.

Returns

insertBefore (exist, add)

Insert new node before old node within the container.

Returns

Examples

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

last ()

The container’s last child.

Type: Node

Examples

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

on (event, visitor?, type?)

Add visitor for next PostCSS walk.

Visitor subscribes for events. Each event contain node type (atrule, rule, decl, comment) and phase (enter, exit) separated with dot. The default phase is enter. As result possible events could be like comment.enter, decl.exit or rule (equal to rule.enter).

PostCSS will walk through CSS AST and call visitor according current node. Visitor will receive node and node’s index.

Returns

Examples

css.on('decl', (node, index) => {
  if (node.prop === 'will-change') {
    node.cloneBefore({ prop: 'backface-visibility', value: 'hidden' })
  }
})

prepend (children)

Inserts new nodes to the start of the container.

Returns

Examples

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

removeAll ()

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

Returns

Examples

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

removeChild (child)

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

Returns

Examples

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

replaceValues (pattern, opts, callback)

Passes all declaration values within the container that match pattern through callback, replacing those values with the returned result of callback.

This method is useful if you are using a custom unit or function and need to iterate through all values.

Returns

Examples

root.replaceValues(/\d+rem/, { fast: 'rem' }, string => {
  return 15 * parseInt(string) + 'px'
})

some (condition)

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

Returns

Examples

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

toResult (opts = {})

Returns a Result instance representing the root’s CSS.

Returns

Examples

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

walk (callback)

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.

Returns

Examples

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

walkAtRules (name?, callback)

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.

Returns

Examples

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

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

walkComments (callback)

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.

Returns

Examples

root.walkComments(comment => {
  comment.remove()
})

walkDecls (prop?, callback)

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.

Returns

Examples

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

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

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

walkRules (selector?, callback)

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.

Returns

Examples

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

append (children)

Inserts new nodes to the end of the container.

Returns

Examples

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

each (callback)

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.

Returns

Examples

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

every (condition)

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

Returns

Examples

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

first ()

The container’s first child.

Type: Node

Examples

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

index (child)

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

Returns

Examples

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

insertAfter (exist, add)

Insert new node after old node within the container.

Returns

insertBefore (exist, add)

Insert new node before old node within the container.

Returns

Examples

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

last ()

The container’s last child.

Type: Node

Examples

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

prepend (children)

Inserts new nodes to the start of the container.

Returns

Examples

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

removeAll ()

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

Returns

Examples

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

removeChild (child)

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

Returns

Examples

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

replaceValues (pattern, opts, callback)

Passes all declaration values within the container that match pattern through callback, replacing those values with the returned result of callback.

This method is useful if you are using a custom unit or function and need to iterate through all values.

Returns

Examples

root.replaceValues(/\d+rem/, { fast: 'rem' }, string => {
  return 15 * parseInt(string) + 'px'
})

selectors ()

An array containing the rule’s individual selectors. Groups of selectors are split at commas.

Type: Array<string>

Examples

const root = postcss.parse('a, b { }')
const rule = root.first

rule.selector  //=> 'a, b'
rule.selectors //=> ['a', 'b']

rule.selectors = ['a', 'strong']
rule.selector //=> 'a, strong'

some (condition)

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

Returns

Examples

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

walk (callback)

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.

Returns

Examples

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

walkAtRules (name?, callback)

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.

Returns

Examples

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

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

walkComments (callback)

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.

Returns

Examples

root.walkComments(comment => {
  comment.remove()
})

walkDecls (prop?, callback)

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.

Returns

Examples

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

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

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

walkRules (selector?, callback)

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.

Returns

Examples

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

type ()

Type to filter warnings from Result#messages. Always equal to "warning".

Type: string

Examples

const nonWarning = result.messages.filter(i => i.type !== 'warning')

text ()

The warning message.

Type: string

Examples

warning.text //=> 'Try to avoid !important'

line ()

Line in the input file with this warning’s source.

Type: number

Examples

warning.line //=> 5

column ()

Column in the input file with this warning’s source.

Type: number

Examples

warning.column //=> 6

toString ()

Returns a warning position and message.

Returns

Examples

warning.toString() //=> 'postcss-lint:a.css:10:14: Avoid !important'

space (string)

Safely splits space-separated values (such as those for background, border-radius, and other shorthand properties).

Returns

Examples

postcss.list.space('1px calc(10% + 1px)') //=> ['1px', 'calc(10% + 1px)']

comma (string)

Safely splits comma-separated values (such as those for transition-* and background properties).

Returns

Examples

postcss.list.comma('black, linear-gradient(white, black)')
//=> ['black', 'linear-gradient(white, black)']

plugin (name, initializer)

Creates a PostCSS plugin with a standard API.

The newly-wrapped function will provide both the name and PostCSS version of the plugin.

const processor = postcss([replace])
processor.plugins[0].postcssPlugin  //=> 'postcss-replace'
processor.plugins[0].postcssVersion //=> '6.0.0'

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

const cleaner = postcss.plugin('postcss-cleaner', () => {
  return (root, result) => {
    result.root = postcss.root()
  }
})

As a convenience, plugins also expose a process method so that you can use them as standalone tools.

cleaner.process(css, processOpts, pluginOpts)
// This is equivalent to:
postcss([ cleaner(pluginOpts) ]).process(css, processOpts)

Asynchronous plugins should return a Promise instance.

postcss.plugin('postcss-import', () => {
  return (root, result) => {
    return new Promise( (resolve, reject) => {
      fs.readFile('base.css', (base) => {
        root.prepend(base)
        resolve()
      })
    })
  }
})

Add warnings using the Node#warn method. Send data to other plugins using the Result#messages array.

postcss.plugin('postcss-caniuse-test', () => {
  return (root, result) => {
    root.walkDecls(decl => {
      if (!caniuse.support(decl.prop)) {
        decl.warn(result, 'Some browsers do not support ' + decl.prop)
      }
    })
  }
})

Returns

stringify (node, builder)

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

Returns

parse (css, opts?)

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

Returns

Examples

// 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

vendor ()

Contains the vendor module.

Type: vendor

Examples

postcss.vendor.unprefixed('-moz-tab') //=> ['tab']

list ()

Contains the list module.

Type: list

Examples

postcss.list.space('5px calc(10% + 5px)') //=> ['5px', 'calc(10% + 5px)']

comment (defaults?)

Creates a new Comment node.

Returns

Examples

postcss.comment({ text: 'test' })

atRule (defaults?)

Creates a new AtRule node.

Returns

Examples

postcss.atRule({ name: 'charset' }).toString() //=> "@charset"

decl (defaults?)

Creates a new Declaration node.

Returns

Examples

postcss.decl({ prop: 'color', value: 'red' }).toString() //=> "color: red"

rule (defaults?)

Creates a new Rule node.

Returns

Examples

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

root (defaults?)

Creates a new Root node.

Returns

Examples

postcss.root({ after: '\n' }).toString() //=> "\n"

prefix (prop)

Returns the vendor prefix extracted from an input string.

Returns

Examples

postcss.vendor.prefix('-moz-tab-size') //=> '-moz-'
postcss.vendor.prefix('tab-size')      //=> ''

unprefixed (prop)

Returns the input string stripped of its vendor prefix.

Returns

Examples

postcss.vendor.unprefixed('-moz-tab-size') //=> 'tab-size'