postcss

constructor

constructor(defaults?: AtRule.AtRuleProps);

property name

name: string;

• The at-rule’s name immediately follows the @.

  const root  = postcss.parse('@media print {}')
  const media = root.first
  media.name //=> 'media'

property nodes

nodes: Node.ChildNode[];

• 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

property params

params: string;

• The at-rule’s parameters, the values that follow the at-rule’s name but precede any {} block.

  const root  = postcss.parse('@media print, screen {}')
  const media = root.first
  media.params //=> 'print, screen'

property parent

parent: ContainerWithChildren<Node.ChildNode>;

property raws

raws: AtRule.AtRuleRaws;

property type

type: string;

method assign

assign: (overrides: AtRule.AtRuleProps | object) => this;

method clone

clone: (overrides?: Partial<AtRule.AtRuleProps>) => this;

method cloneAfter

cloneAfter: (overrides?: Partial<AtRule.AtRuleProps>) => this;

method cloneBefore

cloneBefore: (overrides?: Partial<AtRule.AtRuleProps>) => this;

constructor

constructor(defaults?: Comment.CommentProps);

property parent

parent: Container<Node.ChildNode>;

property raws

raws: Comment.CommentRaws;

property text

text: string;

• The comment's text.

property type

type: string;

method assign

assign: (overrides: Comment.CommentProps | object) => this;

method clone

clone: (overrides?: Partial<Comment.CommentProps>) => this;

method cloneAfter

cloneAfter: (overrides?: Partial<Comment.CommentProps>) => this;

method cloneBefore

cloneBefore: (overrides?: Partial<Comment.CommentProps>) => this;

property first

readonly first: Node;

• The container’s first child.

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

property last

readonly last: Node;

• The container’s last child.

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

property nodes

nodes: Child[];

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

method append

append: (...nodes: Container.NewChild[]) => this;

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

  Parameter nodes

  New nodes. This node for methods chain.

method assign

assign: (overrides: Container.ContainerProps | object) => this;

method clone

clone: (overrides?: Partial<Container.ContainerProps>) => this;

method cloneAfter

cloneAfter: (overrides?: Partial<Container.ContainerProps>) => this;

method cloneBefore

cloneBefore: (overrides?: Partial<Container.ContainerProps>) => this;

method each

each: (
    callback: (node: Child, index: number) => false | void
) => false | undefined;

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

  Parameter callback

  Iterator receives each node and index. Returns false if iteration was broke.

method every

every: (
    condition: (node: Child, index: number, nodes: Child[]) => boolean
) => boolean;

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

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

  Parameter condition

  Iterator returns true or false. Is every child pass condition.

method index

index: (child: Child | number) => number;

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

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

  Parameter child

  Child of the current container. Child index.

method insertAfter

insertAfter: (oldNode: Child | number, newNode: Container.NewChild) => this;

• Insert new node after old node within the container.

  Parameter oldNode

  Child or child’s index.

  Parameter newNode

  New node. This node for methods chain.

method insertBefore

insertBefore: (oldNode: Child | number, newNode: Container.NewChild) => this;

• Insert new node before old node within the container.

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

  Parameter oldNode

  Child or child’s index.

  Parameter newNode

  New node. This node for methods chain.

method normalize

protected normalize: (
    nodes: Container.NewChild,
    sample: Node | undefined,
    type?: 'prepend' | false
) => Child[];

• An internal method that converts a NewChild into a list of actual child nodes that can then be added to this container.

  This ensures that the nodes' parent is set to this container, that they use the correct prototype chain, and that they're marked as dirty.

  Parameter mnodes

  The new node or nodes to add.

  Parameter sample

  A node from whose raws the new node's before raw should be taken.

  Parameter type

  This should be set to 'prepend' if the new nodes will be inserted at the beginning of the container.

method prepend

prepend: (...nodes: Container.NewChild[]) => this;

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

  Parameter nodes

  New nodes. This node for methods chain.

method push

push: (child: Child) => this;

• Add child to the end of the node.

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

  Parameter child

  New node. This node for methods chain.

method removeAll

removeAll: () => this;

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

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

  This node for methods chain.

method removeChild

removeChild: (child: Child | number) => this;

• 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

  Parameter child

  Child or child’s index. This node for methods chain.

method replaceValues

replaceValues: {
    (
        pattern: RegExp | string,
        replaced: string | ((substring: string, ...args: any[]) => string)
    ): this;
    (
        pattern: string | RegExp,
        options: Container.ValueOptions,
        replaced: string | ((substring: string, ...args: any[]) => string)
    ): this;
};

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

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

  Parameter pattern

  Replace pattern.

  Parameter options

  Options to speed up the search.

  Parameter replaced

  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. This node for methods chain.

method some

some: (
    condition: (node: Child, index: number, nodes: Child[]) => boolean
) => boolean;

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

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

  Parameter condition

  Iterator returns true or false. Is some child pass condition.

method walk

walk: (
    callback: (node: ChildNode, index: number) => false | void
) => false | undefined;

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

  Parameter callback

  Iterator receives each node and index. Returns false if iteration was broke.

method walkAtRules

walkAtRules: {
    (
        nameFilter: RegExp | string,
        callback: (atRule: AtRule, index: number) => false | void
    ): false | undefined;
    (callback: (atRule: AtRule, index: number) => false | void): false;
};

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

  Parameter name

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

  Parameter callback

  Iterator receives each node and index. Returns false if iteration was broke.

method walkComments

walkComments: {
    (callback: (comment: Comment, indexed: number) => false | void):
        | false
        | undefined;
    (callback: (comment: Comment, indexed: number) => false | void): false;
};

method walkDecls

walkDecls: {
    (
        propFilter: RegExp | string,
        callback: (decl: Declaration, index: number) => false | void
    ): false | undefined;
    (callback: (decl: Declaration, index: number) => false | void): false;
};

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

  Parameter prop

  String or regular expression to filter declarations by property name.

  Parameter callback

  Iterator receives each node and index. Returns false if iteration was broke.

method walkRules

walkRules: {
    (
        selectorFilter: RegExp | string,
        callback: (rule: Rule, index: number) => false | void
    ): false | undefined;
    (callback: (rule: Rule, index: number) => false | void): false;
};

• 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`)

  Parameter selector

  String or regular expression to filter rules by selector.

  Parameter callback

  Iterator receives each node and index. Returns false if iteration was broke.

constructor

constructor(
    message: string,
    lineOrStartPos?: number | CssSyntaxError.RangePosition,
    columnOrEndPos?: number | CssSyntaxError.RangePosition,
    source?: string,
    file?: string,
    plugin?: string
);

• Instantiates a CSS syntax error. Can be instantiated for a single position or for a range.

  Parameter message

  Error message.

  Parameter lineOrStartPos

  If for a single position, the line number, or if for a range, the inclusive start position of the error.

  Parameter columnOrEndPos

  If for a single position, the column number, or if for a range, the exclusive end position of the error.

  Parameter source

  Source code of the broken file.

  Parameter file

  Absolute path to the broken file.

  Parameter plugin

  PostCSS plugin name, if error came from plugin.

property column

column?: number;

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

property endColumn

endColumn?: number;

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

property endLine

endLine?: number;

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

property file

file?: string;

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

property input

input?: FilePosition;

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

property line

line?: number;

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

property message

message: string;

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

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

property name

name: string;

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

property plugin

plugin?: string;

• Plugin name, if error came from plugin.

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

property reason

reason: string;

• Error message.

  error.message //=> 'Unclosed block'

property source

source?: string;

• Source code of the broken file.

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

property stack

stack: string;

method showSourceCode

showSourceCode: (color?: boolean) => string;

• 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 {"

  Parameter color

  Whether arrow will be colored red by terminal color codes. By default, PostCSS will detect color support by process.stdout.isTTY and process.env.NODE_DISABLE_COLORS. Few lines of CSS source that caused the error.

method toString

toString: () => string;

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

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

  Error position, message and source code.

constructor

constructor(defaults?: Declaration.DeclarationProps);

property important

important: boolean;

• It represents a specificity of the declaration.

  If true, the CSS declaration will have an [important](https://developer.mozilla.org/en-US/docs/Web/CSS/important) specifier.

  const root = postcss.parse('a { color: black !important; color: red }')
  
  root.first.first.important //=> true
  root.first.last.important  //=> undefined

property parent

parent: ContainerWithChildren<Node.ChildNode>;

property prop

prop: string;

• The property name for a CSS declaration.

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

property raws

raws: Declaration.DeclarationRaws;

property type

type: string;

property value

value: string;

• The property value for a CSS declaration.

  Any CSS comments inside the value string will be filtered out. CSS comments present in the source value will be available in the raws property.

  Assigning new value would ignore the comments in raws property while compiling node to string.

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

property variable

readonly variable: boolean;

• It represents a getter that returns true if a declaration starts with -- or $, which are used to declare variables in CSS and SASS/SCSS.

  const root = postcss.parse(':root { --one: 1 }')
  const one = root.first.first
  
  one.variable //=> true

  const root = postcss.parse('$one: 1')
  const one = root.first
  
  one.variable //=> true

method assign

assign: (overrides: Declaration.DeclarationProps | object) => this;

method clone

clone: (overrides?: Partial<Declaration.DeclarationProps>) => this;

method cloneAfter

cloneAfter: (overrides?: Partial<Declaration.DeclarationProps>) => this;

method cloneBefore

cloneBefore: (overrides?: Partial<Declaration.DeclarationProps>) => this;

constructor

constructor(defaults?: Document.DocumentProps);

property nodes

nodes: Root[];

property parent

parent: undefined;

property type

type: string;

method assign

assign: (overrides: Document.DocumentProps | object) => this;

method clone

clone: (overrides?: Partial<Document.DocumentProps>) => this;

method cloneAfter

cloneAfter: (overrides?: Partial<Document.DocumentProps>) => this;

method cloneBefore

cloneBefore: (overrides?: Partial<Document.DocumentProps>) => this;

method toResult

toResult: (options?: ProcessOptions) => Result;

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

  Parameter opts

  Options. Result with current document’s CSS.

constructor

constructor(css: string, opts?: ProcessOptions<Document_ | Root_>);

• Parameter css

  Input CSS source.

  Parameter opts

  Process options.

property css

css: string;

• Input CSS source.

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

property file

file?: string;

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

property from

readonly from: string;

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

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

property hasBOM

hasBOM: boolean;

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

property id

id?: string;

• 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>"

property map

map: PreviousMap;

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

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

method error

error: {
    (
        message: string,
        start: { column: number; line: number } | { offset: number },
        end: { column: number; line: number } | { offset: number },
        opts?: { plugin?: CssSyntaxError['plugin'] }
    ): CssSyntaxError;
    (
        message: string,
        line: number,
        column: number,
        opts?: { plugin?: string }
    ): CssSyntaxError;
    (
        message: string,
        offset: number,
        opts?: { plugin?: string }
    ): CssSyntaxError;
};

• Returns CssSyntaxError with information about the error and its position.

method fromOffset

fromOffset: (offset: number) => { col: number; line: number } | null;