HAST Utility for Parsing HTML

2.0.3 · active · verified Sun Apr 19

hast-util-from-html is a utility within the unifiedjs ecosystem that transforms serialized HTML strings into a HAST (Hypertext Abstract Syntax Tree) representation. The current stable version is 2.0.3. It maintains a relatively active release cadence, with recent patch releases addressing type issues and a major version bump (2.0.0) introducing significant changes like ESM-only support and Node.js 16+ requirement. This package is designed for scenarios where developers need to manually manipulate HTML syntax trees, offering granular control over parsing. It differentiates itself from `parse5` (a low-level HTML parser) by directly producing HAST nodes, and from higher-level abstractions like `rehype-parse`. For browser environments, `hast-util-from-html-isomorphic` offers a lighter, albeit less feature-rich, alternative.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` `hast-util-from-html` in a CommonJS environment, which is an ESM-only package since v2.0.0.

fix Switch to ES module `import` syntax: `import { fromHtml } from 'hast-util-from-html'` and ensure your project is configured to run ESM.
```
SyntaxError: Named export 'fromHtml' not found. The requested module 'hast-util-from-html' does not provide an export named 'fromHtml'
```
cause This error can occur in environments where a CommonJS `require` call is used, or when incorrectly trying to import named exports from an ESM module in some configurations.

fix Verify that your project is using `import { fromHtml } from 'hast-util-from-html'` and that your environment (Node.js version, bundler config) supports ESM correctly.
```
TypeError: fromHtml is not a function
```
cause This often happens if you try to `require` the package and destructure an non-existent default export, or if your import statement is incorrect (e.g., trying to import a default when it's a named export).

fix For ESM, ensure you use `import { fromHtml } from 'hast-util-from-html'`. If you are using an older version (pre-v2) with CommonJS, ensure you're accessing the correct export property if it wasn't the default.

Warnings

breaking Version 2.0.0 and above require Node.js 16 or higher. Using older Node.js versions will result in runtime errors.
Fix: Upgrade your Node.js environment to version 16 or newer.
breaking Since version 2.0.0, the package is ESM-only. CommonJS `require()` statements are no longer supported and will lead to `ERR_REQUIRE_ESM` errors.
Fix: Migrate your codebase to use ES module `import` syntax (e.g., `import { fromHtml } from 'hast-util-from-html'`) and ensure your project is configured for ESM.
breaking Version 2.0.0 introduced the `exports` field in `package.json`. Direct imports of internal or non-public paths (e.g., `hast-util-from-html/lib/foo`) 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-from-html'`).
gotcha By default, `fromHtml` parses input as a complete HTML document, potentially inserting `<html>`, `<head>`, and `<body>` elements around your input. If you intend to parse only a snippet, use the `fragment: true` option.
Fix: For parsing HTML fragments, use `fromHtml(value, { fragment: true })`.
gotcha HTML parse errors are handled by an internal `parse5` parser. By default, these errors might be silently corrected or lead to unexpected tree structures. Configure the `onerror` option to control severity or provide a custom handler.
Fix: Review the API documentation for `OnError`, `ErrorCode`, and `ErrorSeverity` to customize how parse errors are reported or handled via the `onerror` option.

Install

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

Imports

fromHtml
wrong:
```
const { fromHtml } = require('hast-util-from-html')
```
correct:
```
import { fromHtml } from 'hast-util-from-html'
```
Package is ESM-only since v2.0.0; Node.js 16+ is required. CommonJS `require` is not supported for direct imports.
ErrorCode
```
import type { ErrorCode } from 'hast-util-from-html'
```
This is a TypeScript type, defining known parse error codes. For JavaScript users, it's not directly imported but describes values used in options.
Options
```
import type { Options } from 'hast-util-from-html'
```
This is a TypeScript type, describing the configuration object for `fromHtml`. For JavaScript users, it's not directly imported but defines the shape of the `options` argument.

Quickstart

Demonstrates how to parse a simple HTML string into a HAST (Hypertext Abstract Syntax Tree) using the `fromHtml` function, showcasing both fragment and full document parsing.

import { fromHtml } from 'hast-util-from-html';
import type { Root } from 'hast';

const htmlInput = '<h1>Hello, <em>world</em>!</h1><p>This is a paragraph.</p>';

// Parse as a document fragment to avoid automatic <html>, <head>, <body> insertion.
const tree: Root = fromHtml(htmlInput, { fragment: true });

console.log(JSON.stringify(tree, null, 2));

// Example of parsing as a full document
const documentHtml = '<!DOCTYPE html><html><head><title>Test</title></head><body><h1>Doc</h1></body></html>';
const docTree: Root = fromHtml(documentHtml);
console.log('\n--- Full Document Parse ---\n');
console.log(JSON.stringify(docTree, null, 2));

view raw JSON →