What is a PostCSS node?

PostCSS parses CSS into an Abstract Syntax Tree (AST) of nodes. Every node has a type property identifying it — root, atrule, rule, decl or comment. Plugins read and mutate these nodes to transform the stylesheet before it is stringified back to CSS.

What is the difference between a Rule and an AtRule?

A Rule has a selector and a block of declarations, like .a { color: red }. An AtRule starts with @ — its name property holds the keyword (media, supports, import) and params holds the text after it. AtRules may or may not have a body of nested nodes.

How do I traverse all declarations?

Call root.walkDecls(callback) to visit every Declaration in the tree, or pass a filter like walkDecls('color', cb) or a regex. There are matching walkRules, walkAtRules and walkComments helpers, plus a generic walk that visits every node type.

How do I remove or replace a node?

Call node.remove() to delete it, node.replaceWith(newNode) to swap it, or node.cloneBefore() / cloneAfter() to duplicate. Containers expose append, prepend and insertBefore/insertAfter to add children. Mutations are reflected in the final stringified CSS.

What does the plugin Once hook receive?

A PostCSS plugin's Once(root, helpers) hook receives the Root node and a helpers object containing the node constructors (Declaration, Rule, AtRule, Comment) plus result and the parser. Visitor hooks like Declaration(decl) are called per matching node during a single pass.

PostCSS Built-in Node Types

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

The PostCSS node tree

PostCSS turns a stylesheet into a tree of typed nodes. A Root contains Rule and AtRule children; rules and at-rules contain Declaration and Comment nodes. Plugins walk this tree, read properties like selector, prop and value, and mutate or replace nodes — then PostCSS stringifies the tree back to CSS. This reference lists each built-in node type and the API you use to transform it.

How it works

Every node carries a type string and links to its parent. Containers (Root, Rule, AtRule) hold a nodes array of children and expose walk* helpers to traverse them:

module.exports = () => ({
  postcssPlugin: "demo",
  Once(root, { Declaration }) {
    root.walkDecls("color", (decl) => {
      if (decl.value === "red") decl.value = "#f00";
    });
    root.walkAtRules("media", (atRule) => {
      // atRule.name === "media", atRule.params === "(min-width: 768px)"
    });
  },
});
module.exports.postcss = true;

Walk callbacks run depth-first. Returning nothing continues; calling decl.remove() or rule.replaceWith(...) mutates the tree in place.

Tips and notes

Prefer the visitor API (Declaration(decl, helpers)) over Once + walk* for plugins that compose well — PostCSS batches a single AST pass.
Use node.clone() before reusing a node elsewhere; nodes can only have one parent.
decl.important is a boolean, not part of value; preserve it when rewriting.
atRule.nodes is undefined for statement at-rules like @import, and an array for block at-rules like @media.