HAST Utility to Create Nodes from CSS Selectors

3.0.1 · active · verified Sun Apr 19

hast-util-from-selector is a utility package within the unified ecosystem designed to parse CSS selectors and generate corresponding HAST (Hypertext Abstract Syntax Tree) element nodes. It is currently at version 3.0.1, supporting Node.js 16 and later, and adheres to an ESM-only distribution model. The project follows a release cadence tied to Node.js LTS versions, with major versions introducing breaking changes aligned with Node.js support lifecycles or significant internal architectural shifts, such as the move to ESM in v2 and Node.js 16 requirement in v3. This package distinguishes itself from `hast-util-parse-selector` by offering more powerful and complex selector parsing capabilities, akin to `hastscript` but specifically focused on creating HAST elements from selector strings rather than a full hyperscript API. It's an active project, receiving regular updates for dependencies and type refinements.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to import an ESM-only package using CommonJS `require()` syntax.

fix Update your import statements to use ES Modules syntax: `import { fromSelector } from 'hast-util-from-selector'`.
```
Error: Cannot find module 'hast-util-from-selector'
```
cause This typically occurs when using an unsupported older Node.js version (before 16) or if your build tooling isn't configured for ESM.

fix Ensure your Node.js environment is version 16 or higher. If using a bundler (e.g., Webpack, Rollup), ensure it's configured to handle ESM packages correctly.
```
TypeError: (0 , hast_util_from_selector__WEBPACK_IMPORTED_MODULE_0__.fromSelector) is not a function
```
cause This error, often seen with bundlers, suggests an attempt to import a named export as a default, or incorrect CJS/ESM interop.

fix Verify that you are using a named import: `import { fromSelector } from 'hast-util-from-selector'`, as the package has no default export.
```
Error: Unknown selector: ':has'
```
cause Using advanced or non-standard CSS selectors not yet supported by the package's CSS Selectors Level 4 parser.

fix Refer to the CSS Selectors Level 4 specification and the package's documentation for supported selector types. Simplify your selector or use a different method to construct complex HAST nodes.

Warnings

breaking Version 3.0.0 and later require Node.js 16 or higher. Earlier Node.js versions are not supported.
Fix: Upgrade your Node.js environment to version 16 or newer.
breaking The package migrated to be ESM-only since version 2.0.0. CommonJS `require()` is no longer supported for direct imports.
Fix: Update your import statements to use ES Modules syntax: `import { fromSelector } from 'hast-util-from-selector'`.
breaking In version 3.0.0, the `space` option can no longer be passed directly as a second argument. It must now be provided within an options object.
Fix: Change `fromSelector(selector, 'svg')` to `fromSelector(selector, { space: 'svg' })`.
breaking Version 3.0.0 updated its selector parsing to align with the CSS Selectors Level 4 specification. While generally backward-compatible, users should validate complex or edge-case selectors.
Fix: Review and test any complex or unusual CSS selectors to ensure they parse as expected under the CSS Selectors Level 4 specification.
gotcha Using `hast-util-from-selector` with untrusted or unsanitized CSS selector strings can introduce Cross-Site Scripting (XSS) vulnerabilities, as malicious attributes or elements could be injected into the HAST tree.
Fix: Always sanitize or validate any user-provided or external CSS selector strings before passing them to `fromSelector` to prevent XSS attacks.

Install

npm install hast-util-from-selector npm
yarn add hast-util-from-selector yarn
pnpm add hast-util-from-selector pnpm

Imports

fromSelector

wrong:

const fromSelector = require('hast-util-from-selector')

correct:

import { fromSelector } from 'hast-util-from-selector'

ESM-only since v2.0.0. There is no default export.

Options

import type { Options } from 'hast-util-from-selector'

Import for TypeScript type definitions.

Space
```
import type { Space } from 'hast-util-from-selector'
```
Import for TypeScript type definitions, defining 'html' or 'svg' namespace.

Quickstart

Demonstrates parsing a complex CSS selector string into a HAST element tree.

import { fromSelector } from 'hast-util-from-selector';

const selectorString = 'p svg[viewbox="0 0 10 10"] circle[cx=10][cy=10][r=10]';
const hastNode = fromSelector(selectorString);

console.log(JSON.stringify(hastNode, null, 2));
/*
Yields:
{
  "type": "element",
  "tagName": "p",
  "properties": {},
  "children": [
    {
      "type": "element",
      "tagName": "svg",
      "properties": {
        "viewBox": "0 0 10 10"
      },
      "children": [
        {
          "type": "element",
          "tagName": "circle",
          "properties": {
            "cx": "10",
            "cy": "10",
            "r": "10"
          },
          "children": []
        }
      ]
    }
  ]
}
*/

view raw JSON →