{"id":11007,"library":"hast-util-is-element","title":"HAST Element Check Utility","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-is-element","tags":["javascript","unist","hast","hast-util","util","utility","html","is","element","typescript"],"install":[{"cmd":"npm install hast-util-is-element","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-is-element","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-is-element","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v2, explicitly requiring Node.js 16+ since v3. CommonJS `require` is not supported.","wrong":"const isElement = require('hast-util-is-element').isElement","symbol":"isElement","correct":"import { isElement } from 'hast-util-is-element'"},{"note":"Used to generate a pre-optimized check function for repeated use. ESM-only.","wrong":"const convertElement = require('hast-util-is-element').convertElement","symbol":"convertElement","correct":"import { convertElement } from 'hast-util-is-element'"},{"note":"These are TypeScript types for defining custom test functions and element checks. Since v3, avoid explicit type parameters and prefer these new type names.","symbol":"Check, Test, TestFunction","correct":"import type { Check, Test, TestFunction } from 'hast-util-is-element'"}],"quickstart":{"code":"import { isElement } from 'hast-util-is-element';\nimport { type Element, type Text } from 'hast'; // Assuming 'hast' types are installed\n\n// Example HAST nodes\nconst textNode: Text = { type: 'text', value: 'foo' };\nconst anchorNode: Element = { type: 'element', tagName: 'a', properties: { href: '#' }, children: [] };\nconst divNode: Element = { type: 'element', tagName: 'div', properties: { id: 'main', class: ['container', 'flex'] }, children: [] };\nconst imgNode: Element = { type: 'element', tagName: 'img', properties: { src: 'image.png' }, children: [] };\n\nconsole.log('Is textNode an element?', isElement(textNode)); // => false\nconsole.log('Is anchorNode an element?', isElement(anchorNode)); // => true\nconsole.log('Is anchorNode an \"a\" element?', isElement(anchorNode, 'a')); // => true\nconsole.log('Is imgNode an \"img\" element?', isElement(imgNode, 'img')); // => true\nconsole.log('Is anchorNode a \"b\" element?', isElement(anchorNode, 'b')); // => false\nconsole.log('Is divNode an \"a\" or \"div\" element?', isElement(divNode, ['a', 'div'])); // => true\n\n// More complex test using a predicate function\nconsole.log('Is divNode a div with class \"container\"?', \n  isElement(divNode, (node) => node.tagName === 'div' && (node.properties?.class as string[])?.includes('container'))); // => true","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate your project to use ES modules (`import`/`export`) or stick to an older version (<3.0.0) if CommonJS is strictly required.","message":"Version 3.0.0 and later are ESM-only. Importing via CommonJS `require()` is no longer supported and will lead to runtime errors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your Node.js environment is version 16 or newer. Upgrade Node.js if necessary.","message":"Version 3.0.0 and later require Node.js 16 or higher due to ESM-only distribution and other ecosystem updates.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Only use the public API as exported from the main package entry point (`import { ... } from 'hast-util-is-element'`).","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your TypeScript code to use the new type names: `Check`, `Test`, `TestFunction`. Remove explicit type parameters where they are no longer necessary.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `hast-util-is-element` using CommonJS `require()` syntax in a Node.js environment.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported"},{"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.","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.","error":"TypeError: (0 , hast_util_is_element_1.isElement) is not a function"},{"fix":"Update your TypeScript code to use the new type names introduced in v3: `Check`, `Test`, or `TestFunction`.","cause":"Attempting to use old TypeScript types like `AssertPredicate` after upgrading to version 3.0.0.","error":"Property 'AssertPredicate' does not exist on type 'typeof import(\"hast-util-is-element\")'"}],"ecosystem":"npm"}