AST format

September 2, 2024 ยท View on GitHub

CSSTree's AST consists of nodes (leaves). Each node is an object with a set of properties that depends on node's type. Nodes can refer to other nodes and contain a list of nested nodes.

Interactively explore the AST with AST Explorer.

Example

Assume we have a CSS:

body {
    color: red;
}

An AST for this CSS might look like:

{
    type: 'StyleSheet',
    loc: null,
    children: [
        {
            type: 'Rule',
            loc: null,
            prelude: {
                type: 'SelectorList',
                loc: null,
                children: [
                    {
                        type: 'Selector',
                        loc: null,
                        children: [
                            {
                                type: 'TypeSelector',
                                loc: null,
                                name: 'body'
                            }
                        ]
                    }
                ]
            },
            block: {
                type: 'Block',
                loc: null,
                children: [
                    {
                        type: 'Declaration',
                        loc: null,
                        important: false,
                        property: 'color',
                        value: {
                            type: 'Value',
                            loc: null,
                            children: [
                                {
                                    type: 'Identifier',
                                    loc: null,
                                    name: 'red'
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

NOTE: The example uses arrays for the values of the property children. In fact, the values of this property are instances of the List class.

An AST structure (i.e. details level, include positions or not) is depend on options passed to parser. See Parsing CSS into AST for details.

Common node's properties

All nodes have the following properties.

type

Type: String

Indicates the type of a node. The possible values are the ones listed in the Node types below.

loc

Type: Object or null

Information about the position in the source string that corresponds to the node. It has the following structure:

{
    source: String,
    start: {
        offset: Number,
        line: Number,
        column: Number
    },
    end: {
        offset: Number,
        line: Number,
        column: Number
    }
}

The source property contains value of options.filename if passed to csstree.parse(), otherwise "<unknown>".

The offset number is zero-based, indicates the index in a source string passed to the parser.

The line and column numbers are 1-based: the first line is 1 and the first column of a line is 1.

The loc property lets you know from which source file the node comes from (if available) and what part of that file was parsed into the node. By default parser doesn't include loc data into the AST (sets null for this property), you should pass options.positions equal to true to make loc filled.

children

Type: List or null

Only certain types of nodes can contain this property, such as StyleSheet or Block. However, this is the only property that can store a list of nested nodes.

Most node types always store an instance of the List in this property, even if there is no nested nodes (the list is empty). Only some node types, such as PseudoClassSelector and PseudoElementSelector, can store a null instead of a list. This is due to the fact that in the absence of a list such node types is represent a pseudo-selector, and in the presence of a list, a functional pseudo-selector. See definition of each node type for details.

Node types

NOTE: Despite every node has a loc property, this property is excluded from definitions to reduce a noise.

AnPlusB

Used for the An+B microsyntax.

type AnPlusB = {
    type: "AnPlusB";
    a: string | null;
    b: string | null;
}

a or b fields may have no value (equals to null) but not both at the same time. Parser normalizes a value to store a valid integer, i.e. parser will store -1 for -n and 1 for n.

Atrule

type Atrule = {
    type: "Atrule";
    name: string;
    prelude: AtrulePrelude | Raw | null;
    block: Block | null;
}

AtrulePrelude

type AtrulePrelude = {
    type: "AtrulePrelude";
    children: List<any>;
}

AttributeSelector

type AttributeSelector = {
    type: "AttributeSelector";
    name: Identifier;
    matcher: string | null;
    value: String | Identifier | null;
    flags: string | null;
}

Block

type Block = {
    type: "Block";
    children: List<Atrule | Rule | Declaration>;
}

Brackets

type Brackets = {
    type: "Brackets";
    children: List<any>;
}

CDC

type CDC = {
    type: "CDC";
}

CDO

type CDO = {
    type: "CDO";
}

ClassSelector

type ClassSelector = {
    type: "ClassSelector";
    name: string;
}

Combinator

type Combinator = {
    type: "Combinator";
    name: string;
}

Comment

type Comment = {
    type: "Comment";
    value: string;
}

Condition

type Condition = {
    type: "Condition";
    kind: string;
    children: List<Identifier | Feature | FeatureFunction | FeatureRange | SupportsDeclaration>;
}

Declaration

type Declaration = {
    type: "Declaration";
    important: boolean | string;
    property: string;
    value: Value | Raw;
}

DeclarationList

type DeclarationList = {
    type: "DeclarationList";
    children: List<Declaration | Atrule | Rule>;
}

Dimension

type Dimension = {
    type: "Dimension";
    value: string;
    unit: string;
}

Feature

type Feature = {
    type: "Feature";
    kind: string;
    name: string;
    value: Identifier | Number | Dimension | Ratio | Function | null;
}

FeatureFunction

type FeatureFunction = {
    type: "FeatureFunction";
    kind: string;
    feature: string;
    value: Declaration | Selector;
}

FeatureRange

type FeatureRange = {
    type: "FeatureRange";
    kind: string;
    left: Identifier | Number | Dimension | Ratio | Function;
    leftComparison: string;
    middle: Identifier | Number | Dimension | Ratio | Function;
    rightComparison: string | null;
    right: Identifier | Number | Dimension | Ratio | Function | null;
}

Function

type Function = {
    type: "Function";
    name: string;
    children: List<any>;
}

GeneralEnclosed

type GeneralEnclosed = {
    type: "GeneralEnclosed";
    kind: string;
    function: string | null;
    children: List<any>;
}

Hash

type Hash = {
    type: "Hash";
    value: string;
}

IdSelector

type IdSelector = {
    type: "IdSelector";
    name: string;
}

Identifier

type Identifier = {
    type: "Identifier";
    name: string;
}

Layer

type Layer = {
    type: "Layer";
    name: string;
}

LayerList

type LayerList = {
    type: "LayerList";
    children: List<Layer>;
}

MediaQuery

type MediaQuery = {
    type: "MediaQuery";
    modifier: string | null;
    mediaType: string | null;
    condition: Condition | null;
}

MediaQueryList

type MediaQueryList = {
    type: "MediaQueryList";
    children: List<MediaQuery>;
}

NestingSelector

type NestingSelector = {
    type: "NestingSelector";
}

Nth

type Nth = {
    type: "Nth";
    nth: AnPlusB | Identifier;
    selector: SelectorList | null;
}

Number

type Number = {
    type: "Number";
    value: string;
}

Operator

type Operator = {
    type: "Operator";
    value: string;
}

Parentheses

type Parentheses = {
    type: "Parentheses";
    children: List<any>;
}

Percentage

type Percentage = {
    type: "Percentage";
    value: string;
}

PseudoClassSelector

type PseudoClassSelector = {
    type: "PseudoClassSelector";
    name: string;
    children: List<Raw> | null;
}

PseudoElementSelector

type PseudoElementSelector = {
    type: "PseudoElementSelector";
    name: string;
    children: List<Raw> | null;
}

Ratio

type Ratio = {
    type: "Ratio";
    left: Number | Function;
    right: Number | Function | null;
}

Raw

A sequence of any characters. This node type is used for unparsed fragments of CSS, e.g. due to parse error or parser settings, and for quirk parts like content of some functions, such as url() or expression().

type Raw = {
    type: "Raw";
    value: string;
}

Rule

type Rule = {
    type: "Rule";
    prelude: SelectorList | Raw;
    block: Block;
}

Scope

type Scope = {
    type: "Scope";
    root: SelectorList | Raw | null;
    limit: SelectorList | Raw | null;
}

Selector

type Selector = {
    type: "Selector";
    children: List<TypeSelector | IdSelector | ClassSelector | AttributeSelector | PseudoClassSelector | PseudoElementSelector | Combinator>;
}

SelectorList

type SelectorList = {
    type: "SelectorList";
    children: List<Selector | Raw>;
}

String

A sequence of characters enclosed in double quotes or single quotes.

type String = {
    type: "String";
    value: string;
}

StyleSheet

type StyleSheet = {
    type: "StyleSheet";
    children: List<Comment | CDO | CDC | Atrule | Rule | Raw>;
}

SupportsDeclaration

type SupportsDeclaration = {
    type: "SupportsDeclaration";
    declaration: Declaration;
}

TypeSelector

type TypeSelector = {
    type: "TypeSelector";
    name: string;
}

UnicodeRange

Used for the Unicode-Range microsyntax.

type UnicodeRange = {
    type: "UnicodeRange";
    value: string;
}

Url

type Url = {
    type: "Url";
    value: string;
}

Value

type Value = {
    type: "Value";
    children: List<any>;
}

WhiteSpace

A sequence of one or more white spaces, i.e. (space), \t, \r, \n and \f.

type WhiteSpace = {
    type: "WhiteSpace";
    value: string;
}