css-select

library7.0.0jsnpmunverified

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.

web-framework

npm install css-select

github ↗package ↗

INSTALL

IMPORT

SIG · CSS-SELECT

css-select

web-frameworkjavascriptv7.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cssSelect

✓ import cssSelect from 'css-select'

✗ const cssSelect = require('css-select')

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

isTag

✓ import { isTag } from 'css-select'

✗ import { isTag } from 'css-select/lib/general'

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

✓ import { filters } from 'css-select'

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

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

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);

Debug

Known issues

breakingESM 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.

affects: >=7.0.0

breakingDeep 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.

affects: >=5.0.0

deprecatedRe-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.

affects: >=5.0.0

deprecated_compileToken export is deprecated since v5 and removed in v7.

fix

Use _compileUnsafe instead.

affects: >=5.0.0

gotchaRelative 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.

affects: >=5.1.0

gotchaThe 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.).

affects: >=3.0.0

Errors

Common errors & fixes

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

Using deprecated _compileToken export that was removed in v7.

fix

Replace _compileToken with _compileUnsafe.

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

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.

SyntaxError: Unexpected token /

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

fix

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

Upgrade

Version history

7.0.0latest on npm

Audit

Dependencies

css-whatrequiredRequired. Parses CSS selectors into an AST for compilation.

domhandleroptionalOptional. Default DOM structure when using built-in adapter; alternative adapters can be used without it.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/fb55/css-select ↗

packagehttps://www.npmjs.com/package/css-select ↗