HAST Interactive Content Utility

3.0.0 · active · verified Sun Apr 19

hast-util-interactive is a focused utility within the unified ecosystem, specifically designed to determine if a given hast (Hypertext Abstract Syntax Tree) node constitutes "interactive content" according to the HTML specification. This package is particularly useful for tools that analyze or transform HTML content and need to identify elements like `<a>` with `href`, `<button>`, `<input>`, or `<video controls>` to enforce accessibility rules, validate content, or apply specific styling. The current stable version is 3.0.0. Maintained by the syntax-tree collective, it follows a release cadence tied to Node.js LTS cycles and hast ecosystem updates, providing TypeScript types for enhanced developer experience. Its primary differentiator is its precise implementation of the HTML interactive content algorithm for hast nodes, offering a reliable predicate function rather than a full parsing or transformation engine.

Common errors

```
TypeError [ERR_REQUIRE_ESM]: require() of ES module /path/to/node_modules/hast-util-interactive/index.js from /your/project/file.js not supported.
```
cause Attempting to use CommonJS `require()` syntax with an ESM-only package.

fix Change your import statement from `const { interactive } = require('hast-util-interactive')` to `import { interactive } from 'hast-util-interactive'` and ensure your Node.js environment or build setup supports ESM.
```
ReferenceError: interactive is not defined
```
cause Using an outdated Node.js version (prior to 16) that does not meet the minimum requirement for `hast-util-interactive@^3`, or an incorrect import.

fix Upgrade your Node.js environment to version 16 or higher. Alternatively, ensure the `import` statement is correct and the module is resolving properly.
```
TypeError: Cannot read properties of undefined (reading 'type') or similar error when passing non-node values.
```
cause Passing `null`, `undefined`, or other non-Node JavaScript values to the `interactive` function, which now strictly requires a `hast` Node.

fix Before calling `interactive(node)`, validate that `node` is indeed a `hast` Node object. For example, `if (node && typeof node === 'object' && node.type) { interactive(node) }`.

Warnings

breaking Version 3.0.0 changes to require Node.js 16 or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or newer. For projects requiring older Node.js, use `hast-util-interactive@^2`.
breaking Version 3.0.0 removes support for passing non-Node values (e.g., `null`, `undefined`) to the `interactive` function. Input must be a valid `hast` Node.
Fix: Ensure that the `node` argument passed to `interactive()` is always a valid `hast` Node object. Validate input before calling the utility.
breaking Version 3.0.0 introduces `exports` in package.json, changing internal module resolution. Avoid relying on private, non-exported APIs as they may no longer be accessible.
Fix: Always import symbols directly from the package's main entry point, e.g., `import { interactive } from 'hast-util-interactive'`. Do not try to access internal paths like `hast-util-interactive/lib/interactive.js`.
breaking Version 2.0.0 converted the package to ESM (ECMAScript Modules) only. CommonJS `require()` is no longer supported.
Fix: Update your import statements to use ES module syntax (e.g., `import { interactive } from 'hast-util-interactive'`). Ensure your project is configured for ESM, or use a tool like Babel/TypeScript to transpile.
gotcha This utility is highly specific, checking for 'interactive content' according to HTML. It is not a general-purpose HTML parser or validator. Its definition of 'interactive' is precise (e.g., `<a>` is only interactive with an `href`).
Fix: Understand the HTML specification for interactive content before use. This utility serves a niche purpose within the unified ecosystem.

Install

npm install hast-util-interactive npm
yarn add hast-util-interactive yarn
pnpm add hast-util-interactive pnpm

Imports

interactive
wrong:
```
const interactive = require('hast-util-interactive')
```
correct:
```
import { interactive } from 'hast-util-interactive'
```
This package is ESM-only since v2.0.0 and requires Node.js 16+ since v3.0.0. CommonJS `require()` is not supported.
Element
```
import type { Element } from 'hast'
```
While this package ships its own types, input nodes often come from the 'hast' package, requiring its types for full type safety.

Quickstart

Demonstrates how to use the `interactive` function to check various hast nodes against the HTML specification for interactive content.

import { interactive } from 'hast-util-interactive';
import type { Element, Text, Root } from 'hast';

// Example 1: Non-interactive anchor (no href)
const nonInteractiveLink: Element = {
  type: 'element',
  tagName: 'a',
  properties: {},
  children: [{type: 'text', value: 'Non-clickable link'}]
};
console.log('Is nonInteractiveLink interactive?', interactive(nonInteractiveLink)); // => false

// Example 2: Interactive anchor (with href)
const interactiveLink: Element = {
  type: 'element',
  tagName: 'a',
  properties: {href: '#section'},
  children: [{type: 'text', value: 'Clickable link'}]
};
console.log('Is interactiveLink interactive?', interactive(interactiveLink)); // => true

// Example 3: Interactive button
const buttonElement: Element = {
  type: 'element',
  tagName: 'button',
  properties: {},
  children: [{type: 'text', value: 'Submit'}]
};
console.log('Is buttonElement interactive?', interactive(buttonElement)); // => true

// Example 4: Video with controls
const videoElement: Element = {
  type: 'element',
  tagName: 'video',
  properties: {controls: true, src: 'movie.mp4'},
  children: []
};
console.log('Is videoElement interactive?', interactive(videoElement)); // => true

// Example 5: Input field
const inputElement: Element = {
  type: 'element',
  tagName: 'input',
  properties: {type: 'text', value: 'Hello'},
  children: []
};
console.log('Is inputElement interactive?', interactive(inputElement)); // => true

view raw JSON →