{"id":25142,"library":"css-select","title":"css-select","description":"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.","status":"active","version":"7.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/fb55/css-select","tags":["javascript","css","selector","sizzle","typescript"],"install":[{"cmd":"npm install css-select","lang":"bash","label":"npm"},{"cmd":"yarn add css-select","lang":"bash","label":"yarn"},{"cmd":"pnpm add css-select","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required. Parses CSS selectors into an AST for compilation.","package":"css-what","optional":false},{"reason":"Optional. Default DOM structure when using built-in adapter; alternative adapters can be used without it.","package":"domhandler","optional":true}],"imports":[{"note":"ESM-only since v7. CommonJS require() is not supported.","wrong":"const cssSelect = require('css-select')","symbol":"cssSelect","correct":"import cssSelect from 'css-select'"},{"note":"Deep imports (e.g., 'css-select/lib/...') are not permitted since v5. Use named exports from the package root.","wrong":"import { isTag } from 'css-select/lib/general'","symbol":"isTag","correct":"import { isTag } from 'css-select'"},{"note":"Compiles a selector string into a function. Available since v4.","symbol":"compile","correct":"import { compile } from 'css-select'"},{"note":"filters is deprecated since v5, use `pseudos` option instead. Deep import removed in v7.","wrong":"const filters = require('css-select/lib/pseudo-selectors/filters')","symbol":"filters","correct":"import { filters } from 'css-select'"}],"quickstart":{"code":"import cssSelect, { compile } from 'css-select';\nimport { parseDocument } from 'htmlparser2';\nimport { getElementsByTagName } from 'domutils';\n\nconst html = '

Hello

World

';\nconst dom = parseDocument(html);\n\n// Use cssSelect to find elements matching a selector\nconst paragraphs = cssSelect('p', dom);\nconsole.log('Number of

elements:', paragraphs.length);\n\n// Compile a selector into a reusable function\nconst isContainerDiv = compile('.container');\nconst container = paragraphs.find(el => el.parent && isContainerDiv(el.parent));\nconsole.log('Parent container tag:', container?.parent?.name || 'N/A');\n\n// With options (e.g., pseudos)\nconst buttons = cssSelect('button:enabled', dom, { pseudos: { }});\nconsole.log('Buttons:', buttons.length);","lang":"typescript","description":"Demonstrates basic usage of cssSelect and compile functions with htmlparser2 DOM, including selector compilation and options."},"warnings":[{"fix":"Use import syntax or migrate to Node.js >=20.19.0 if you must use require() via dynamic import.","message":"ESM only in v7+; CommonJS require() does not work.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Use root package imports only. For types, import from 'css-select' directly.","message":"Deep imports (e.g., 'css-select/lib/...') are no longer permitted since v5.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Use the `pseudos` option in cssSelect() instead of extending these objects.","message":"Re-exports of aliases, filters, and pseudos are deprecated since v5 and removed in v7.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Use _compileUnsafe instead.","message":"_compileToken export is deprecated since v5 and removed in v7.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Set `relativeSelector: false` option to disable context-scoping.","message":"Relative selectors are enabled by default: selectors are relative to the passed context (no parent matching above context).","severity":"gotcha","affected_versions":">=5.1.0"},{"fix":"Provide an `adapter` option implementing the required methods (isTag, getChildren, etc.).","message":"The default adapter works with domhandler nodes. If using a custom DOM structure, you must provide an adapter object.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Replace _compileToken with _compileUnsafe.","cause":"Using deprecated _compileToken export that was removed in v7.","error":"Error: The `_compileToken` export has been removed. Use `_compileUnsafe` instead."},{"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.","cause":"Passing a string selector directly to cssSelect without parsing first; or using an unsupported DOM node without an adapter.","error":"TypeError: Cannot read properties of undefined (reading 'type')"},{"fix":"Remove unsupported syntax; css-select does not support regex selectors.","cause":"Using a regex-like syntax in selector (e.g., /regex/ is not supported).","error":"SyntaxError: Unexpected token /"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}