css-selector-parser
Advanced tools
A high-performance CSS selector parser with advanced features for modern web development.
🎮 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 to selectors-4progressive: latest + accepts unknown pseudo-classes, pseudo-elements and attribute case sensitivity modifiersSee 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 arrayCSS 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.
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.
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 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 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.
FAQs
Powerful and compliant CSS selector parser.
The npm package css-selector-parser receives a total of 2,408,719 weekly downloads. As such, css-selector-parser popularity was classified as popular.
We found that css-selector-parser demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.
Research
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.