css-select

1.3.0-rc0 verified Fri May 01 auth: no javascript

A CSS selector compiler/engine that turns CSS selectors into functions for testing and querying DOM elements. Current stable version is 2.x (v1.3.0-rc0 is a pre-release of a UMD build). It uses right-to-left execution for efficient O(n) performance, unlike left-to-right engines like Sizzle. Features full CSS3 selectors, partial jQuery extensions, and uses domhandler/domutils as default DOM adapter. Released regularly via npm; TypeScript types included since v1.3.0. Key differentiator: performance through right-to-left compilation and a function-stack approach.

Common errors

error TypeError: CSSselect is not a function ↓

cause Using CommonJS require on an ESModule default export without proper interop.

fix

Use 'import CSSselect from 'css-select-umd'' or 'const CSSselect = require('css-select-umd').default'

error Cannot find module 'domhandler' ↓

cause Missing peer dependency domhandler which is required for default DOM structure.

fix

Install domhandler: npm install domhandler

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

cause Passing a non-DOM element or invalid DOM node to CSSselect.

fix

Ensure you pass a valid DOM tree (e.g., from domhandler) and that elements have a 'type' property.

Warnings

breaking Version 1.3.0-rc0 is a pre-release of a UMD build; API may change before stable release. ↓

fix Use stable version 2.x instead or pin to exact pre-release version.

gotcha The package name is 'css-select-umd' but exports are identical to 'css-select' UMD build; ensure you use correct import path. ↓

fix Import from 'css-select-umd' or from 'css-select' if not using UMD.

deprecated Older versions (<2.0) of the underlying 'css-select' used a different API; 'css-select-umd' is based on v1 branch and may not have newer features. ↓

fix Upgrade to css-select v2+ for latest API and use 'css-select' package directly instead of UMD bundle if possible.

gotcha CSSselect throws errors on invalid selectors; this differs from jQuery which silently ignores them. ↓

fix Wrap selector calls in try-catch or validate selectors before passing to CSSselect.

Install

npm install css-select-umd

yarn add css-select-umd

pnpm add css-select-umd

Imports

CSSselect
wrong
```
const CSSselect = require('css-select-umd')
```
correct
```
import CSSselect from 'css-select-umd'
```
ESM default import; for CommonJS use require('css-select-umd') but the UMD build also supports global scope.

selectOne

wrong

import CSSselect from 'css-select-umd'; CSSselect.selectOne(...)

correct

import { selectOne } from 'css-select-umd'

selectOne is a named export; do not access as a method of default import.

compile
wrong
```
const compile = require('css-select').compile
```
correct
```
import { compile } from 'css-select-umd'
```
compile is a named export; available as a side-effect of importing the package.

Quickstart

Shows how to import and use css-select-umd to query DOM elements from parsed HTML using htmlparser2.

import CSSselect from 'css-select-umd';
import { DomHandler } from 'domhandler';
import { parseDocument } from 'htmlparser2';

const html = '<div><p class="foo">Hello</p><p class="bar">World</p></div>';
const handler = new DomHandler((err, dom) => {
  if (err) throw err;
  const elements = CSSselect('p.foo', dom);
  console.log(elements.length); // 1
  console.log(elements[0].children[0].data); // 'Hello'
});
parseDocument(html, handler);