HAST Element Check Utility

3.0.0 · active · verified Sun Apr 19

This package, `hast-util-is-element`, is a fundamental utility within the HAST (Hypertext Abstract Syntax Tree) ecosystem, primarily designed to check if a given HAST node represents an HTML element. It offers flexible testing capabilities, allowing developers to verify not only if a node is an element but also if it matches specific tag names, an array of tag names, or even complex criteria through a predicate function. The library is currently stable at version 3.0.0, which introduced significant changes, including a migration to ESM-only distribution and a requirement for Node.js 16 or newer. Its release cadence is generally tied to updates within the broader syntax-tree ecosystem, including HAST type definition improvements and Node.js version alignment. A key differentiator is its specialized focus on HAST nodes, providing a more targeted and potentially performant alternative compared to the more generic `unist-util-is` for general Unist nodes. For advanced matching based on CSS selectors, `hast-util-select` offers more robust capabilities, positioning `hast-util-is-element` as a lightweight yet powerful tool for basic and custom element checks.

Common errors

```
ERR_REQUIRE_ESM: require() of ES Module ... not supported
```
cause Attempting to import `hast-util-is-element` using CommonJS `require()` syntax in a Node.js environment.

fix Change `const { isElement } = require('hast-util-is-element');` to `import { isElement } from 'hast-util-is-element';` and ensure your project is configured for ESM.
```
TypeError: (0 , hast_util_is_element_1.isElement) is not a function
```
cause This typically indicates an incorrect import statement for an ESM module in a CommonJS context, or a bundling issue where the named export is not correctly resolved.

fix Verify that you are using `import { isElement } from 'hast-util-is-element';` in an ESM context. If using a bundler, check its ESM/CommonJS compatibility settings.
```
Property 'AssertPredicate' does not exist on type 'typeof import("hast-util-is-element")'
```
cause Attempting to use old TypeScript types like `AssertPredicate` after upgrading to version 3.0.0.

fix Update your TypeScript code to use the new type names introduced in v3: `Check`, `Test`, or `TestFunction`.

Warnings

breaking Version 3.0.0 and later are ESM-only. Importing via CommonJS `require()` is no longer supported and will lead to runtime errors.
Fix: Migrate your project to use ES modules (`import`/`export`) or stick to an older version (<3.0.0) if CommonJS is strictly required.
breaking Version 3.0.0 and later require Node.js 16 or higher due to ESM-only distribution and other ecosystem updates.
Fix: Ensure your Node.js environment is version 16 or newer. Upgrade Node.js if necessary.
breaking The package now uses the `exports` field in `package.json`. Direct deep imports (e.g., `hast-util-is-element/lib/some-internal-file`) are no longer supported and will break.
Fix: Only use the public API as exported from the main package entry point (`import { ... } from 'hast-util-is-element'`).
breaking Type parameter changes in v3.0.0. Old types like `AssertAnything` and `AssertPredicate` have been replaced by `Check`, `Test`, and `TestFunction`. Explicit type parameters should generally be avoided.
Fix: Update your TypeScript code to use the new type names: `Check`, `Test`, `TestFunction`. Remove explicit type parameters where they are no longer necessary.
gotcha The `isElement` function will throw an error if an incorrect `test`, `index`, or `parent` argument is provided. However, it will not throw an error if the `element` argument is not a valid HAST node or not an element type, instead returning `false`.
Fix: Always ensure that `test`, `index`, and `parent` arguments conform to the expected types and structure to avoid runtime errors. Validate `element` type before calling if strict node type checking is needed.

Install

npm install hast-util-is-element npm
yarn add hast-util-is-element yarn
pnpm add hast-util-is-element pnpm

Imports

isElement
wrong:
```
const isElement = require('hast-util-is-element').isElement
```
correct:
```
import { isElement } from 'hast-util-is-element'
```
ESM-only since v2, explicitly requiring Node.js 16+ since v3. CommonJS `require` is not supported.

convertElement

wrong:

const convertElement = require('hast-util-is-element').convertElement

correct:

import { convertElement } from 'hast-util-is-element'

Used to generate a pre-optimized check function for repeated use. ESM-only.

Check, Test, TestFunction
```
import type { Check, Test, TestFunction } from 'hast-util-is-element'
```
These are TypeScript types for defining custom test functions and element checks. Since v3, avoid explicit type parameters and prefer these new type names.

Quickstart

Demonstrates how to use the `isElement` function to check different HAST nodes against various criteria, including tag names, arrays of tag names, and custom predicate functions.

import { isElement } from 'hast-util-is-element';
import { type Element, type Text } from 'hast'; // Assuming 'hast' types are installed

// Example HAST nodes
const textNode: Text = { type: 'text', value: 'foo' };
const anchorNode: Element = { type: 'element', tagName: 'a', properties: { href: '#' }, children: [] };
const divNode: Element = { type: 'element', tagName: 'div', properties: { id: 'main', class: ['container', 'flex'] }, children: [] };
const imgNode: Element = { type: 'element', tagName: 'img', properties: { src: 'image.png' }, children: [] };

console.log('Is textNode an element?', isElement(textNode)); // => false
console.log('Is anchorNode an element?', isElement(anchorNode)); // => true
console.log('Is anchorNode an "a" element?', isElement(anchorNode, 'a')); // => true
console.log('Is imgNode an "img" element?', isElement(imgNode, 'img')); // => true
console.log('Is anchorNode a "b" element?', isElement(anchorNode, 'b')); // => false
console.log('Is divNode an "a" or "div" element?', isElement(divNode, ['a', 'div'])); // => true

// More complex test using a predicate function
console.log('Is divNode a div with class "container"?', 
  isElement(divNode, (node) => node.tagName === 'div' && (node.properties?.class as string[])?.includes('container'))); // => true

view raw JSON →