{"id":12301,"library":"unist-util-select","title":"Unist Node Selector Utility","description":"unist-util-select is a utility designed to query and match nodes within a unist (Universal Syntax Tree) abstract syntax tree using CSS-like selectors. The package is currently at stable version 5.1.0 and maintains an active release cadence, with multiple minor and major updates in the past year, reflecting ongoing development and adherence to modern JavaScript standards. Key differentiators include its ability to work with any unist syntax tree and select all node types, providing equivalents to DOM's `querySelector`, `querySelectorAll`, and `matches`. However, it's important to note that unlike the DOM, unist nodes do not inherently store parent references, meaning certain parent-sensitive selectors (e.g., `:first-child`) will not function as they do in a browser environment. For performance-critical scenarios involving numerous modifications, alternatives like `unist-util-visit` might be more efficient, as `unist-util-select` walks the entire tree on each call. For `hast` (HTML AST) specific element selections, `hast-util-select` is recommended.","status":"active","version":"5.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-select","tags":["javascript","unist","unist-util","util","utility","visit","tree","ast","node","typescript"],"install":[{"cmd":"npm install unist-util-select","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-select","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-select","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package only provides named exports. Since v4.0.0, it is ESM-only, so CommonJS `require()` is not supported.","wrong":"import matches from 'unist-util-select'","symbol":"matches","correct":"import { matches } from 'unist-util-select'"},{"note":"unist-util-select is ESM-only since v4.0.0. The `require()` syntax will result in a runtime error.","wrong":"const { select } = require('unist-util-select')","symbol":"select","correct":"import { select } from 'unist-util-select'"},{"note":"Use specific named imports for `selectAll` as there is no default export and wildcard imports are typically not desired for a single function.","wrong":"import * as selectAll from 'unist-util-select'","symbol":"selectAll","correct":"import { selectAll } from 'unist-util-select'"}],"quickstart":{"code":"import { u } from 'unist-builder';\nimport { matches, select, selectAll } from 'unist-util-select';\n\nconst tree = u('blockquote', [\n  u('paragraph', [u('text', 'Alpha')]),\n  u('paragraph', [u('text', 'Bravo')]),\n  u('code', 'Charlie'),\n  u('paragraph', [u('text', 'Delta')]),\n  u('paragraph', [u('text', 'Echo')]),\n  u('paragraph', [u('text', 'Foxtrot')]),\n  u('paragraph', [u('text', 'Golf')])\n]);\n\nconsole.log('Matches blockquote or list:', matches('blockquote, list', tree));\n\nconst selectedNode = select('code ~ :nth-child(even)', tree);\nconsole.log('Selected single node (Delta):', selectedNode ? selectedNode.children[0].value : 'None');\n\nconst allSelectedNodes = selectAll('code ~ :nth-child(even)', tree);\nconsole.log('Selected all nodes (Delta, Foxtrot):', allSelectedNodes.map(node => node.children[0].value));\n","lang":"typescript","description":"Demonstrates how to use `matches`, `select`, and `selectAll` to query a unist tree with CSS-like selectors, including handling different selector types and multiple results."},"warnings":[{"fix":"Upgrade Node.js to version 16 or higher, or pin to `unist-util-select@^4`.","message":"Version 5.0.0 changed the minimum Node.js requirement to 16. Ensure your environment meets this minimum before upgrading.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Migrate all imports to use ES module syntax (e.g., `import { select } from 'unist-util-select'`).","message":"Since version 4.0.0, the package is ESM-only and uses the `exports` map. CommonJS `require()` statements will no longer work and will lead to runtime errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update existing code to expect and handle `undefined` instead of `null` for no match.","message":"In version 5.0.0, the `select` and `selectAll` functions now yield `undefined` instead of `null` when no matching node is found.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Refactor logic to manually traverse parent/child relationships using `unist-util-visit` or `unist-util-parents` for context, or use simpler, node-specific selectors.","message":"Parent-sensitive CSS selectors (e.g., `:first-child`, `:last-child`, `>`) are not supported. unist nodes do not store references to their parents, making these selectors impossible to evaluate directly.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Consider optimizing operations that repeatedly query the tree. For complex modifications, use `unist-util-visit` to traverse once and make changes, or cache selection results if appropriate.","message":"Frequent use of `select` or `selectAll` on large unist trees can be inefficient as each call involves walking the entire tree. For scenarios requiring many changes or bulk operations, `unist-util-visit` might offer better performance.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statements to use ES module syntax: `import { select } from 'unist-util-select';`","cause":"Attempting to use CommonJS `require()` syntax for `unist-util-select` in an environment where it's treated as an ES module.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Ensure you are using named ES module imports: `import { matches } from 'unist-util-select';`","cause":"This error typically occurs if `matches` (or `select`/`selectAll`) is imported incorrectly, such as attempting a default import or incorrectly destructuring named exports from a CommonJS `require()` call.","error":"TypeError: matches is not a function"},{"fix":"Revise your selector to avoid parent-sensitive pseudo-classes. If parent context is strictly needed, you may need to pre-process your tree (e.g., with `unist-util-parents`) or perform manual checks during traversal.","cause":"This error indicates an attempt to use a parent-sensitive CSS pseudo-class (like `:first-child`, `:last-child`, `:nth-child` without context) which is not supported by `unist-util-select` due to the lack of parent references in unist nodes.","error":"Error: Unknown pseudo-class :first-child"}],"ecosystem":"npm"}