AtRule

AtRule

Represents an at-rule.

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

Constructor

new AtRule()

Source:
Example
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   //=> []

Extends

Members

first :Node

Source:
Inherited From:

The container’s first child.

Type:
Example
rule.first === rules.nodes[0]

last :Node

Source:
Inherited From:

The container’s last child.

Type:
Example
rule.last === rule.nodes[rule.nodes.length - 1]

nodes :Array.<Node>

Source:
Overrides:

An array containing the container’s children.

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

Methods

append(…children) → {Node}

Source:
Overrides:

Inserts new nodes to the end of the container.

Example
const decl1 = postcss.decl({ prop: 'color', value: 'black' })
const decl2 = postcss.decl({ prop: 'background-color', value: 'white' })
rule.append(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')
Parameters:
Name Type Attributes Description
children Node | object | string | Array.<Node> <repeatable>

New nodes.

Returns:

This node for methods chain.

Type
Node

each(callback) → {false|undefined}

Source:
Inherited From:

Iterates through the container’s immediate children, calling callback for each child.

Returning false in the callback will break iteration.

This method only iterates through the container’s immediate children. If you need to recursively iterate through all the container’s descendant nodes, use Container#walk.

Unlike the for {}-cycle or Array#forEach this iterator is safe if you are mutating the array of child nodes during iteration. PostCSS will adjust the current index to match the mutations.

Example
const root = postcss.parse('a { color: black; z-index: 1 }')
const rule = root.first

for (const decl of rule.nodes) {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Cycle will be infinite, because cloneBefore moves the current node
  // to the next index
}

rule.each(decl => {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Will be executed only for color and z-index
})
Parameters:
Name Type Description
callback childIterator

Iterator receives each node and index.

Returns:

Returns false if iteration was broke.

Type
false | undefined

every(condition) → {boolean}

Source:
Inherited From:

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

Example
const noPrefixes = rule.every(i => i.prop[0] !== '-')
Parameters:
Name Type Description
condition childCondition

Iterator returns true or false.

Returns:

Is every child pass condition.

Type
boolean

index(child) → {number}

Source:
Inherited From:

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

Example
rule.index( rule.nodes[2] ) //=> 2
Parameters:
Name Type Description
child Node

Child of the current container.

Returns:

Child index.

Type
number

insertAfter(exist, add) → {Node}

Source:
Inherited From:

Insert new node after old node within the container.

Parameters:
Name Type Description
exist Node | number

Child or child’s index.

add Node | object | string | Array.<Node>

New node.

Returns:

This node for methods chain.

Type
Node

insertBefore(exist, add) → {Node}

Source:
Inherited From:

Insert new node before old node within the container.

Example
rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }))
Parameters:
Name Type Description
exist Node | number

Child or child’s index.

add Node | object | string | Array.<Node>

New node.

Returns:

This node for methods chain.

Type
Node

prepend(…children) → {Node}

Source:
Overrides:

Inserts new nodes to the start of the container.

Example
const decl1 = postcss.decl({ prop: 'color', value: 'black' })
const decl2 = postcss.decl({ prop: 'background-color', value: 'white' })
rule.prepend(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')
Parameters:
Name Type Attributes Description
children Node | object | string | Array.<Node> <repeatable>

New nodes.

Returns:

This node for methods chain.

Type
Node

removeAll() → {Node}

Source:
Inherited From:

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

Example
rule.removeAll()
rule.nodes.length //=> 0
Returns:

This node for methods chain.

Type
Node

removeChild(child) → {Node}

Source:
Inherited From:

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

Example
rule.nodes.length  //=> 5
rule.removeChild(decl)
rule.nodes.length  //=> 4
decl.parent        //=> undefined
Parameters:
Name Type Description
child Node | number

Child or child’s index.

Returns:

This node for methods chain

Type
Node

replaceValues(pattern, opts, callback) → {Node}

Source:
Inherited From:

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

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

Example
root.replaceValues(/\d+rem/, { fast: 'rem' }, string => {
  return 15 * parseInt(string) + 'px'
})
Parameters:
Name Type Description
pattern string | RegExp

Replace pattern.

opts object

Options to speed up the search.

Properties
Name Type Description
props string | Array.<string>

An array of property names.

fast string

String that’s used to narrow down values and speed up the regexp search.

callback function | string

String to replace pattern or callback that returns a new value. The callback will receive the same arguments as those passed to a function parameter of String#replace.

Returns:

This node for methods chain.

Type
Node

some(condition) → {boolean}

Source:
Inherited From:

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

Example
const hasPrefix = rule.some(i => i.prop[0] === '-')
Parameters:
Name Type Description
condition childCondition

Iterator returns true or false.

Returns:

Is some child pass condition.

Type
boolean

walk(callback) → {false|undefined}

Source:
Inherited From:

Traverses the container’s descendant nodes, calling callback for each node.

Like container.each(), this method is safe to use if you are mutating arrays during iteration.

If you only need to iterate through the container’s immediate children, use Container#each.

Example
root.walk(node => {
  // Traverses all descendant nodes.
})
Parameters:
Name Type Description
callback childIterator

Iterator receives each node and index.

Returns:

Returns false if iteration was broke.

Type
false | undefined

walkAtRules(nameopt, callback) → {false|undefined}

Source:
Inherited From:

Traverses the container’s descendant nodes, calling callback for each at-rule node.

If you pass a filter, iteration will only happen over at-rules that have matching names.

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

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

let first = false
root.walkAtRules('charset', rule => {
  if (!first) {
    first = true
  } else {
    rule.remove()
  }
})
Parameters:
Name Type Attributes Description
name string | RegExp <optional>

String or regular expression to filter at-rules by name.

callback childIterator

Iterator receives each node and index.

Returns:

Returns false if iteration was broke.

Type
false | undefined

walkComments(callback) → {false|undefined}

Source:
Inherited From:

Traverses the container’s descendant nodes, calling callback for each comment node.

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

Example
root.walkComments(comment => {
  comment.remove()
})
Parameters:
Name Type Description
callback childIterator

Iterator receives each node and index.

Returns:

Returns false if iteration was broke.

Type
false | undefined

walkDecls(propopt, callback) → {false|undefined}

Source:
Inherited From:

Traverses the container’s descendant nodes, calling callback for each declaration node.

If you pass a filter, iteration will only happen over declarations with matching properties.

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

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

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

root.walkDecls(/^background/, decl => {
  decl.value = takeFirstColorFromGradient(decl.value)
})
Parameters:
Name Type Attributes Description
prop string | RegExp <optional>

String or regular expression to filter declarations by property name.

callback childIterator

Iterator receives each node and index.

Returns:

Returns false if iteration was broke.

Type
false | undefined

walkRules(selectoropt, callback) → {false|undefined}

Source:
Inherited From:

Traverses the container’s descendant nodes, calling callback for each rule node.

If you pass a filter, iteration will only happen over rules with matching selectors.

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

Example
const selectors = []
root.walkRules(rule => {
  selectors.push(rule.selector)
})
console.log(`Your CSS uses ${ selectors.length } selectors`)
Parameters:
Name Type Attributes Description
selector string | RegExp <optional>

String or regular expression to filter rules by selector.

callback childIterator

Iterator receives each node and index.

Returns:

returns false if iteration was broke.

Type
false | undefined