Registry / serialization / hast-util-select

hast-util-select

library6.0.4jsnpmunverified

hast-util-select provides a suite of utilities for querying and matching nodes within a HAST (HTML Abstract Syntax Tree) structure using CSS selectors. It offers functions equivalent to DOM's `matches`, `querySelector`, and `querySelectorAll` for HTML trees. The current stable version is 6.0.4, with active maintenance and a regular release cadence, including recent major updates. A key differentiator is its specific application to HAST, which means it operates differently from DOM selectors in certain aspects, particularly regarding parent-sensitive selectors (e.g., `:first-child`, descendant selectors) due to HAST nodes not storing parent references. While powerful for targeted queries, it advises caution for high-frequency use, suggesting `unist-util-visit` for bulk modifications due to its tree-walking overhead.

serialization

npm install hast-util-select

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-SELECT

hast-util-select

serializationjavascriptv6.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

matches

✓ import { matches } from 'hast-util-select'

✗ const { matches } = require('hast-util-select')

ESM-only since v6. Attempting to use CommonJS `require` will result in a runtime error.

select

✓ import { select } from 'hast-util-select'

✗ import select from 'hast-util-select'

This package uses named exports only. There is no default export.

selectAll

✓ import { selectAll } from 'hast-util-select'

✗ const selectAll = require('hast-util-select').selectAll

For Node.js versions prior to 16, a polyfill for ESM might be required, though v6 explicitly requires Node.js 16+.

Demonstrates how to use `matches`, `select`, and `selectAll` functions with a HAST tree to find and match elements based on CSS selectors.

import {h} from 'hastscript'; import {matches, select, selectAll} from 'hast-util-select'; const tree = h('section', [ h('p', 'Alpha'), h('p', 'Bravo'), h('h1', 'Charlie'), h('p', 'Delta'), h('p', 'Echo'), h('p', 'Foxtrot'), h('p', 'Golf') ]); console.log('Matches section:', matches('section', tree)); // true console.log('Select single:', select('h1 ~ :nth-child(even)', tree)); // Expected output: { type: 'element', tagName: 'p', properties: {}, children: [ { type: 'text', value: 'Delta' } ] } console.log('Select all:', selectAll('h1 ~ :nth-child(even)', tree)); // Expected output: [ // { type: 'element', tagName: 'p', properties: {}, children: [ { type: 'text', value: 'Delta' } ] }, // { type: 'element', tagName: 'p', properties: {}, children: [ { type: 'text', value: 'Foxtrot' } ] } // ]

Debug

Known issues

breakingVersion 6.0.0 changed to be ESM-only and explicitly requires Node.js 16 or higher. CommonJS `require` statements will fail.

fix

Migrate your project to use ESM imports (`import ... from 'pkg'`) and ensure Node.js 16+ is used. Update your `package.json` with `"type": "module"` if necessary for your environment.

affects: >=6.0.0

breakingThe return value for `select` when no node matches changed from `null` to `undefined` in version 6.0.0.

fix

Update your code to expect and handle `undefined` when no element is found, instead of `null`. E.g., `if (node === undefined)` rather than `if (node === null)`.

affects: >=6.0.0

breakingVersion 6.0.0 updated its CSS selector parsing to match CSS Selectors Level 4. While generally compatible, older, non-standard selectors like `:any` are no longer supported and should be replaced with `:is`.

fix

Review and update complex CSS selectors to adhere to modern CSS Selectors Level 4 syntax. Replace `:any` with `:is()` where appropriate.

affects: >=6.0.0

gotchaHAST nodes, unlike DOM nodes, do not maintain references to their parents. This means selectors that rely on parent-child relationships or tree context (e.g., `:first-child`, `p b`, `p > b`, `:nth-child`) will not work with `matches` and may behave unexpectedly or not at all with `select` and `selectAll`.

fix

Avoid parent-sensitive CSS selectors. For operations requiring tree traversal or parent context, consider using utilities like `unist-util-visit` or performing manual tree traversal after selecting direct children.

affects: >=1.0.0

gotchaThis utility walks the entire tree for each call, making it potentially slow if used repeatedly for many small queries. For bulk modifications or processing many nodes, alternative methods might be more performant.

fix

If performance is critical for large trees or frequent operations, consider using `unist-util-visit` to traverse the tree once and apply transformations or checks, rather than multiple calls to `select` or `selectAll`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: require is not a function

Attempting to use `require()` to import `hast-util-select` in an environment that enforces ESM, or after upgrading to v6 without migrating to ESM imports.

fix

Change your import statement from `const { symbol } = require('hast-util-select')` to `import { symbol } from 'hast-util-select'`. Ensure your `package.json` is configured for ESM (`"type": "module"`).

Selector parsing error related to ':any' or similar pseudos

Using outdated CSS pseudo-classes like `:any` that are no longer supported by the updated CSS Selectors Level 4 parsing logic in v6.

fix

Replace `:any` with the standard `:is()` pseudo-class in your selectors. Review other deprecated CSS selectors and update them to modern equivalents.

Result of `select` is `null` but expected `undefined` (or vice-versa)

Code written for `hast-util-select` versions prior to 6.0.0 expected `null` for no match, but v6 returns `undefined`.

fix

Update your conditional checks from `if (node === null)` to `if (node === undefined)` (or `if (!node)` for both `null` and `undefined`).

Upgrade

Version history

6.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/hast-util-select ↗

packagehttps://www.npmjs.com/package/hast-util-select ↗