css-selector-parser

What is css-selector-parser?

The css-selector-parser npm package is a utility for parsing CSS selectors into an abstract syntax tree (AST). This can be useful for various applications such as CSS preprocessing, validation, and transformation.

What are css-selector-parser's main functionalities?

Parsing CSS Selectors

This feature allows you to parse a CSS selector string into an abstract syntax tree (AST). The example code demonstrates how to parse a complex CSS selector and output the resulting AST.

const { CssSelectorParser } = require('css-selector-parser');
const parser = new CssSelectorParser();
parser.registerNestingOperators('>', '+', '~');
parser.registerAttrEqualityMods('^', '$', '*', '~');
const ast = parser.parse('div.class[attr^="value"] > p');
console.log(JSON.stringify(ast, null, 2));

Customizing Parser Behavior

This feature allows you to customize the behavior of the parser by registering different nesting operators and attribute equality modifiers. The example code shows how to enable substitutes and register custom operators.

const { CssSelectorParser } = require('css-selector-parser');
const parser = new CssSelectorParser();
parser.registerNestingOperators('>', '+', '~');
parser.registerAttrEqualityMods('^', '$', '*', '~');
parser.enableSubstitutes();
const ast = parser.parse('div.class[attr^="value"] > p');
console.log(JSON.stringify(ast, null, 2));

Serializing AST to CSS Selector

This feature allows you to serialize an abstract syntax tree (AST) back into a CSS selector string. The example code demonstrates how to parse a CSS selector into an AST and then render it back to a string.

const { CssSelectorParser } = require('css-selector-parser');
const parser = new CssSelectorParser();
parser.registerNestingOperators('>', '+', '~');
parser.registerAttrEqualityMods('^', '$', '*', '~');
const ast = parser.parse('div.class[attr^="value"] > p');
const selector = parser.render(ast);
console.log(selector);

Other packages similar to css-selector-parser

postcss-selector-parser

PostCSS Selector Parser is a tool for parsing, transforming, and stringifying CSS selectors. It is more feature-rich and integrates well with the PostCSS ecosystem, making it suitable for more complex CSS processing tasks.

css-what

css-what is a CSS selector parser that is part of the Cheerio library. It is designed to be fast and efficient, making it a good choice for applications that require high performance.

csstree

CSSTree is a tool for parsing, walking, and generating CSS. It provides a comprehensive set of features for working with CSS, including a detailed AST and various utilities for manipulating CSS. It is more comprehensive compared to css-selector-parser.

README

css-selector-parser

• Fast and low memory CSS selector parser.
• Parses CSS selector into object-model (AST).
• Compliant with all historical and modern CSS specs.
• Covered with tests.
• Documented.
• Supported CSS selector standards:
  • css1: https://www.w3.org/TR/CSS1/
  • css2: https://www.w3.org/TR/CSS2/
  • css3/selectors-3: https://www.w3.org/TR/selectors-3/
  • selectors-4: https://www.w3.org/TR/selectors-4/
  • latest: refers to selectors-4
  • progressive: latest + accepts unknown psudo-classes, psudo-elements and attribute case sensitivity modifiers

Important: Migrating from 1.x.

Installation

npm install css-selector-parser

Usage

Parsing

import {createParser} from 'css-selector-parser';

const parse = createParser();
const selector = parse('a[href^="/"], .container:has(nav) > a[href]:nth-child(2)');

console.log(selector);

Produces:

({
  type: 'Selector',
  rules: [
    {
      type: 'Rule',
      tag: { type: 'TagName', name: 'a' },
      attributes: [
        {
          type: 'Attribute',
          name: 'href',
          operator: '^=',
          value: { type: 'String', value: '/' }
        }
      ]
    },
    {
      type: 'Rule',
      classNames: [ 'container' ],
      pseudoClasses: [
        {
          type: 'PseudoClass',
          name: 'has',
          argument: {
            type: 'Selector',
            rules: [ { type: 'Rule', tag: { type: 'TagName', name: 'nav' } } ]
          }
        }
      ],
      nestedRule: {
        type: 'Rule',
        combinator: '>',
        tag: { type: 'TagName', name: 'a' },
        attributes: [ { type: 'Attribute', name: 'href' } ],
        pseudoClasses: [
          {
            type: 'PseudoClass',
            name: 'nth-child',
            argument: { type: 'Formula', a: 0, b: 2 }
          }
        ]
      }
    }
  ]
})

Constructing AST and rendering

import {ast, render} from 'css-selector-parser';

const selector = ast.selector({
    rules: [
        ast.rule({
            tag: ast.tagName({name: 'a'}),
            attributes: [
                ast.attribute({name: 'href', operator: '^=', value: ast.string({value: '/'})})
            ]
        }),
        ast.rule({
            classNames: ['container'],
            pseudoClasses: [
                ast.pseudoClass({
                    name: 'has',
                    argument: ast.selector({
                        rules: [
                            ast.rule({tag: ast.tagName({name: 'nav'})})
                        ]
                    })
                })
            ],
            nestedRule: ast.rule({
                combinator: '>',
                tag: ast.tagName({name: 'a'}),
                attributes: [ast.attribute({name: 'href'})],
                pseudoClasses: [
                    ast.pseudoClass({
                        name: 'nth-child',
                        argument: ast.formula({a: 0, b: 2})
                    })
                ],
                pseudoElement: 'before'
            })
        })
    ]
});

console.log(render(selector)); // a[href^="/"], .container:has(nav) > a[href]:nth-child(2)::before

API

• Full API Documentation
• Parsing CSS selectors
• Constructing CSS AST
• Rendering CSS AST

LICENSE

MIT

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

Changelog

2.3.2 (2023-06-25)

Bug Fixes

• fix foruma parsing with negative A, closes #28 (824312f)
• include js file extension into the mjs build, closes #22 (f50b350)
• rendering nested selectors with combinators, closes #27 (40fb434)