{"id":11011,"library":"hast-util-parse-selector","title":"HAST Utility to Parse CSS Selectors","description":"`hast-util-parse-selector` is a focused utility within the `unified` ecosystem designed to create HAST (Hypertext Abstract Syntax Tree) element nodes from simple CSS selector strings. Currently at stable version 4.0.0, this package follows semantic versioning, with major releases typically aligning with dropping support for unmaintained Node.js versions. It processes basic selectors that can include a tag name, multiple class names, and a single ID, transforming them into a `hast` element object with corresponding `tagName` and `properties` (including `id` and `className` arrays). While powerful for its specific use case, it explicitly states its niche nature, recommending more comprehensive alternatives like `hastscript` or `hast-util-from-selector` for handling complex CSS selectors. Its primary differentiator is its simplicity and directness in parsing straightforward selectors into HAST nodes, making it suitable for scenarios where a full-blown selector engine is overkill.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-parse-selector","tags":["javascript","unist","hast","hast-util","util","utility","html","css","selector","typescript"],"install":[{"cmd":"npm install hast-util-parse-selector","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-parse-selector","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-parse-selector","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only since v3.0.0. Use `import` statements; `require()` is not supported.","wrong":"const { parseSelector } = require('hast-util-parse-selector')","symbol":"parseSelector","correct":"import { parseSelector } from 'hast-util-parse-selector'"},{"note":"For Deno environments, use the `esm.sh` CDN import path. Ensure the version matches your requirement.","symbol":"parseSelector","correct":"import { parseSelector } from 'https://esm.sh/hast-util-parse-selector@4'"},{"note":"For browser environments, use the `esm.sh` CDN with the `?bundle` query parameter for broader compatibility.","symbol":"parseSelector","correct":"<script type=\"module\"> import { parseSelector } from 'https://esm.sh/hast-util-parse-selector@4?bundle' </script>"}],"quickstart":{"code":"import { parseSelector } from 'hast-util-parse-selector';\nimport type { Element } from 'hast'; // Import for type definition\n\n// Create a HAST element from a complex class/id selector\nconst complexSelectorElement: Element = parseSelector('.quux#bar.baz.qux');\nconsole.log('Complex Selector Result:', complexSelectorElement);\n// Expected: { type: 'element', tagName: 'div', properties: { id: 'bar', className: [ 'quux', 'baz', 'qux' ] }, children: [] }\n\n// Create a HAST element with a specific tag name and ID\nconst spanElement: Element = parseSelector('span#foo');\nconsole.log('Span with ID Result:', spanElement);\n// Expected: { type: 'element', tagName: 'span', properties: { id: 'foo' }, children: [] }\n\n// Create an element with a default tag name when no selector is provided\nconst defaultElement: Element = parseSelector(undefined, 'p');\nconsole.log('Default Tag Name Result:', defaultElement);\n// Expected: { type: 'element', tagName: 'p', properties: {}, children: [] }\n\n// Using an empty string selector also results in the default tag name\nconst emptySelectorElement: Element = parseSelector('');\nconsole.log('Empty Selector Result:', emptySelectorElement);\n// Expected: { type: 'element', tagName: 'div', properties: {}, children: [] }\n\n// Example with a different default tag name\nconst customDefaultElement: Element = parseSelector('.my-class', 'section');\nconsole.log('Custom Default Tag Name Result:', customDefaultElement);\n// Expected: { type: 'element', tagName: 'section', properties: { className: [ 'my-class' ] }, children: [] }","lang":"typescript","description":"Demonstrates how to create `hast` element nodes using various simple CSS selectors and `defaultTagName` options, including class names, IDs, and custom tag fallbacks."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher. Alternatively, use `hast-util-parse-selector@^3` if you must remain on an older Node.js version.","message":"Version 4.0.0 raises the minimum required Node.js version to 16. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update your TypeScript dependency to a newer, supported version (e.g., TS 4.2+). The package is fully typed and expects a modern TypeScript environment.","message":"Version 4.0.0 removed support for TypeScript 4.1. Ensure your project is using a compatible TypeScript version.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always import directly from the package name (`'hast-util-parse-selector'`). Avoid referencing internal paths like `'hast-util-parse-selector/lib/some-module.js'`.","message":"Version 4.0.0 changed to use `exports` in `package.json` for module resolution. Direct imports of internal or private module paths are no longer supported and will break.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Migrate your project to use ES Modules (`import ... from '...'`) or ensure your build system correctly transpiles ESM for CommonJS environments. Avoid `require()` for this package.","message":"Version 3.0.0 converted the package to be ESM-only. CommonJS `require()` statements are no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Never pass unsanitized user input directly to `parseSelector`. If user input is necessary, thoroughly sanitize it using a library like `hast-util-sanitize` before processing.","message":"Using unsanitized user input in the `selector` or `defaultTagName` parameters can lead to a Cross-Site Scripting (XSS) vulnerability. If a `tagName` resolves to `script`, it will inject a script element into the HAST tree.","severity":"gotcha","affected_versions":">=2.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { parseSelector } = require('hast-util-parse-selector');` to `import { parseSelector } from 'hast-util-parse-selector';`. Ensure your project's `package.json` has `\"type\": \"module\"` or that files are `.mjs`.","cause":"Attempting to use `require()` to import `hast-util-parse-selector`, which is an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Verify your import statement is `import { parseSelector } from 'hast-util-parse-selector';` and that your environment supports ESM. If using a bundler, ensure it's configured for ESM.","cause":"This usually indicates an incorrect import or module resolution issue, especially when mixing CommonJS and ESM, or when an invalid import path is used.","error":"TypeError: parseSelector is not a function"},{"fix":"Ensure your `tsconfig.json` includes `\"moduleResolution\": \"bundler\"` (for modern bundlers) or `\"node\"` and `\"allowSyntheticDefaultImports\": true`. Also, update your `typescript` and potentially `@types/hast` dependencies to match the package's requirements (TS 4.2+ for v4.0.0).","cause":"Your TypeScript compiler cannot locate the package's type definitions, possibly due to an outdated TypeScript version, incorrect `moduleResolution` in `tsconfig.json`, or an issue with the `@types/hast` dependency if type inference relies on it.","error":"TS2307: Cannot find module 'hast-util-parse-selector' or its corresponding type declarations."}],"ecosystem":"npm"}