css-select

7.0.0 verified Fri May 01 auth: no javascript

A CSS selector compiler and engine that turns CSS selectors into functions to test or find matching elements in a DOM tree. Current stable version is 7.0.0, released as an ESM-only package requiring Node.js >=20.19.0. The engine uses a right-to-left execution model for optimal performance (O(n) vs O(n^(k+1)) for left-to-right engines). It fully implements CSS3 selectors and most CSS4 selectors, with partial jQuery/Sizzle extension support. Ships TypeScript types. Breaking changes in v7 include removal of CommonJS support, removal of deprecated exports (_compileToken, aliases, filters, pseudos), and no more deep imports. Prior major versions include v6 (dual CJS/ESM, pseudos option, `:where` support) and v5 (adapter API changes). Release cadence is periodic; maintained by fb55.

Common errors

error Error: The `_compileToken` export has been removed. Use `_compileUnsafe` instead. ↓

cause Using deprecated _compileToken export that was removed in v7.

fix

Replace _compileToken with _compileUnsafe.

error TypeError: Cannot read properties of undefined (reading 'type') ↓

cause Passing a string selector directly to cssSelect without parsing first; or using an unsupported DOM node without an adapter.

fix

Ensure you are passing a valid DOM tree from htmlparser2 or provide a proper adapter. Use compile() if you need to test single elements.

error SyntaxError: Unexpected token / ↓

cause Using a regex-like syntax in selector (e.g., /regex/ is not supported).

fix

Remove unsupported syntax; css-select does not support regex selectors.

Warnings

breaking ESM only in v7+; CommonJS require() does not work. ↓

fix Use import syntax or migrate to Node.js >=20.19.0 if you must use require() via dynamic import.

breaking Deep imports (e.g., 'css-select/lib/...') are no longer permitted since v5. ↓

fix Use root package imports only. For types, import from 'css-select' directly.

deprecated Re-exports of aliases, filters, and pseudos are deprecated since v5 and removed in v7. ↓

fix Use the `pseudos` option in cssSelect() instead of extending these objects.

deprecated _compileToken export is deprecated since v5 and removed in v7. ↓

fix Use _compileUnsafe instead.

gotcha Relative selectors are enabled by default: selectors are relative to the passed context (no parent matching above context). ↓

fix Set `relativeSelector: false` option to disable context-scoping.

gotcha The default adapter works with domhandler nodes. If using a custom DOM structure, you must provide an adapter object. ↓

fix Provide an `adapter` option implementing the required methods (isTag, getChildren, etc.).

Install

npm install css-select

yarn add css-select

pnpm add css-select

Imports

cssSelect

wrong

const cssSelect = require('css-select')

correct

import cssSelect from 'css-select'

ESM-only since v7. CommonJS require() is not supported.

isTag
wrong
```
import { isTag } from 'css-select/lib/general'
```
correct
```
import { isTag } from 'css-select'
```
Deep imports (e.g., 'css-select/lib/...') are not permitted since v5. Use named exports from the package root.
compile
```
import { compile } from 'css-select'
```
Compiles a selector string into a function. Available since v4.

filters

wrong

const filters = require('css-select/lib/pseudo-selectors/filters')

correct

import { filters } from 'css-select'

filters is deprecated since v5, use `pseudos` option instead. Deep import removed in v7.

Quickstart

Demonstrates basic usage of cssSelect and compile functions with htmlparser2 DOM, including selector compilation and options.

import cssSelect, { compile } from 'css-select';
import { parseDocument } from 'htmlparser2';
import { getElementsByTagName } from 'domutils';

const html = '<html><body><div class="container"><p id="intro">Hello</p><p>World</p></div></body></html>';
const dom = parseDocument(html);

// Use cssSelect to find elements matching a selector
const paragraphs = cssSelect('p', dom);
console.log('Number of <p> elements:', paragraphs.length);

// Compile a selector into a reusable function
const isContainerDiv = compile('.container');
const container = paragraphs.find(el => el.parent && isContainerDiv(el.parent));
console.log('Parent container tag:', container?.parent?.name || 'N/A');

// With options (e.g., pseudos)
const buttons = cssSelect('button:enabled', dom, { pseudos: { }});
console.log('Buttons:', buttons.length);