Node

Node

All node classes inherit the following common methods.

Constructor

(abstract) new Node(defaultsopt)

Source:
Parameters:
Name Type Attributes Description
defaults object <optional>

Value for node properties.

Members

parent :Container

Source:

The node’s parent node.

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

raws :object

Source:

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

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

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

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

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

source :source

Source:

The input source of the node.

The property is used in source map generation.

If you create a node manually (e.g., with postcss.decl()), that node will not have a source property and will be absent from the source map. For this reason, the plugin developer should consider cloning nodes to create new ones (in which case the new node’s source will reference the original, cloned node) or setting the source property manually.

// Bad
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

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

type :string

Source:

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

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

Methods

after(add) → {Node}

Source:

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

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

Example
decl.after('color: black')
Parameters:
Name Type Description
add Node | object | string | Array.<Node>

New node.

Returns:

This node for methods chain.

Type
Node

before(add) → {Node}

Source:

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

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

Example
decl.before('content: ""')
Parameters:
Name Type Description
add Node | object | string | Array.<Node>

New node.

Returns:

This node for methods chain.

Type
Node

cleanRaws(keepBetweenopt) → {undefined}

Source:

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

Example
node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined
Parameters:
Name Type Attributes Description
keepBetween boolean <optional>

Keep the raws.between symbols.

Returns:
Type
undefined

clone(overridesopt) → {Node}

Source:

Returns an exact clone of the node.

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

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

New properties to override in the clone.

Returns:

Clone of the node.

Type
Node

cloneAfter(overridesopt) → {Node}

Source:

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

Parameters:
Name Type Attributes Description
overrides object <optional>

New properties to override in the clone.

Returns:

New node.

Type
Node

cloneBefore(overridesopt) → {Node}

Source:

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

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

Mew properties to override in the clone.

Returns:

New node

Type
Node

error(message, optsopt) → {CssSyntaxError}

Source:

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

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

This method produces very useful error messages.

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

Error description.

opts object <optional>

Options.

Properties
Name Type Description
plugin string

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

word string

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

index number

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

Returns:

Error object to throw it.

Type
CssSyntaxError

next() → {Node|undefined}

Source:

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

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

Next node.

Type
Node | undefined

prev() → {Node|undefined}

Source:

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

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

Previous node.

Type
Node | undefined

raw(prop, defaultTypeopt) → {string}

Source:

Returns a Node#raws value. If the node is missing the code style property (because the node was manually built or cloned), PostCSS will try to autodetect the code style property by looking at other nodes in the tree.

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

Name of code style property.

defaultType string <optional>

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

Returns:

Code style value.

Type
string

remove() → {Node}

Source:

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

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

Node to make calls chain.

Type
Node

replaceWith(…nodes) → {Node}

Source:

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

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

Mode(s) to replace current one.

Returns:

Current node to methods chain.

Type
Node

root() → {Root}

Source:

Finds the Root instance of the node’s tree.

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

Root parent.

Type
Root

toString(stringifieropt) → {string}

Source:

Returns a CSS string representing the node.

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

A syntax to use in string generation.

Returns:

CSS string of this node.

Type
string

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

Source:

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

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

The Result instance that will receive the warning.

text string

Warning message.

opts object <optional>

Options

Properties
Name Type Description
plugin string

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

word string

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

index number

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

Returns:

Created warning object.

Type
Warning