npm npm bundle size NPM License GitHub stars
A high-performance CSS selector parser with advanced features for modern web development.
- 🚀 Fast and memory-efficient parsing for all CSS selectors
- 🌳 AST-based object model for programmatic manipulation
- 🚶 AST traversal with visitor pattern for analyzing and transforming selectors
- 📊 Full compliance with all CSS selector specifications
- 🧪 Comprehensive test coverage
- 📚 Well-documented API with TypeScript support
- 🔄 Two-way conversion between CSS selectors and AST
- 🧩 Modular support for various CSS specifications
- 🎮 Interactive Playground - Try it in your browser!
🎮 Launch Interactive Playground
Test CSS selectors in your browser with syntax highlighting, real-time AST visualization, and configurable parser options.
css1: W3C CSS1 Specificationcss2: W3C CSS2 Specificationcss3/selectors-3: W3C Selectors Level 3selectors-4: W3C Selectors Level 4latest: refers toselectors-4progressive:latest+ accepts unknown pseudo-classes, pseudo-elements and attribute case sensitivity modifiers
See Changelog for release details.
npm install css-selector-parser # or yarn add css-selector-parser # or pnpm add css-selector-parser
import { createParser } from 'css-selector-parser'; const parse = createParser(); const selector = parse('a[href^="/"], .container:has(nav) > a[href]:nth-child(2)::before'); console.log(selector);
This produces an AST (Abstract Syntax Tree) output:
({ type: 'Selector', rules: [ { type: 'Rule', items: [ { type: 'TagName', name: 'a' }, { type: 'Attribute', name: 'href', operator: '^=', value: { type: 'String', value: '/' } } ] }, { type: 'Rule', items: [ { type: 'ClassName', name: 'container' }, { type: 'PseudoClass', name: 'has', argument: { type: 'Selector', rules: [ { type: 'Rule', items: [ { type: 'TagName', name: 'nav' } ] } ] } } ], nestedRule: { type: 'Rule', items: [ { type: 'TagName', name: 'a' }, { type: 'Attribute', name: 'href' }, { type: 'PseudoClass', name: 'nth-child', argument: { type: 'Formula', a: 0, b: 2 } }, { type: 'PseudoElement', name: 'before' } ], combinator: '>' } } ] })
import { ast, render } from 'css-selector-parser'; const selector = ast.selector({ rules: [ ast.rule({ items: [ ast.tagName({name: 'a'}), ast.attribute({name: 'href', operator: '^=', value: ast.string({value: '/'})}) ] }), ast.rule({ items: [ ast.className({name: 'container'}), ast.pseudoClass({ name: 'has', argument: ast.selector({ rules: [ast.rule({items: [ast.tagName({name: 'nav'})]})] }) }) ], nestedRule: ast.rule({ combinator: '>', items: [ ast.tagName({name: 'a'}), ast.attribute({name: 'href'}), ast.pseudoClass({ name: 'nth-child', argument: ast.formula({a: 0, b: 2}) }), ast.pseudoElement({name: 'before'}) ] }) }) ] }); console.log(render(selector)); // a[href^="/"], .container:has(nav) > a[href]:nth-child(2)::before
The traverse function allows you to walk through the AST and visit each node, making it easy to analyze or transform selectors.
import { createParser, traverse } from 'css-selector-parser'; const parse = createParser(); const selector = parse('div.foo > span#bar:hover::before'); // Simple visitor function - called for each node traverse(selector, (node, context) => { console.log(node.type, context.parents.length); }); // Visitor with enter/exit hooks traverse(selector, { enter(node, context) { console.log('Entering:', node.type); if (node.type === 'ClassName') { console.log('Found class:', node.name); } }, exit(node, context) { console.log('Leaving:', node.type); } }); // Skip visiting children of specific nodes traverse(selector, (node) => { if (node.type === 'PseudoClass') { // Don't visit children of pseudo-classes return false; } }); // Practical example: collect all class names const classNames = []; traverse(selector, (node) => { if (node.type === 'ClassName') { classNames.push(node.name); } }); console.log(classNames); // ['foo'] // Access parent information traverse(selector, (node, context) => { console.log({ type: node.type, parent: context.parent?.type, depth: context.parents.length, key: context.key, index: context.index }); });
The traversal context provides:
node: The current AST node being visitedparent: The parent node (undefined for root)parents: Array of all ancestor nodes from root to currentkey: Property name in parent that references this nodeindex: Array index if this node is in an array
CSS Modules are specifications that add new selectors or modify existing ones. This parser supports various CSS modules that can be included in your syntax definition:
import { createParser } from 'css-selector-parser'; // Create a parser with specific CSS modules enabled const parse = createParser({ syntax: 'selectors-4', modules: ['css-position-3', 'css-scoping-1'] });
| Module | Description |
|---|---|
css-position-1/2/3/4 |
Position-related pseudo-classes |
css-scoping-1 |
Shadow DOM selectors (:host, :host-context(), ::slotted()) |
css-pseudo-4 |
Modern pseudo-elements (::selection, ::backdrop, etc.) |
css-shadow-parts-1 |
::part() for styling shadow DOM components |
css-nesting-1 |
CSS Nesting selector (&) |
The latest syntax automatically includes all modules marked as current specifications.
- Complete API Documentation
- Parsing CSS Selectors
- Constructing CSS AST
- Rendering CSS AST
- Traversing CSS AST
Contributions are welcome! Please feel free to submit a Pull Request.
MIT
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.
If you find this project useful, please consider sponsoring the developer or supporting on Patreon.