HAST to HTML Serializer

9.0.5 · active · verified Sun Apr 19

hast-util-to-html is a core utility within the unifiedjs ecosystem, designed to serialize a HAST (Hypertext Abstract Syntax Tree) into an HTML string. It is currently at version 9.0.5 and maintains an active release cadence, providing frequent patch updates and introducing major versions for significant breaking changes or feature additions. This utility is distinct from `rehype-stringify`, which acts as a higher-level wrapper for integrating with rehype plugins, while `hast-util-to-html` offers direct, granular control over the serialization process. Its primary differentiators include extensive options for configuring the output, enabling use cases from pretty-printing to minification, and its direct compatibility with HAST trees. It serves as the inverse operation to `hast-util-from-html`, providing a complete round-trip for HTML processing within the unifiedjs framework. The package adheres to modern JavaScript standards, being ESM-only since version 9.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` an ESM-only package in a CommonJS context.

fix Migrate your project to use ES modules (`import`/`export`) or switch to an older version of `hast-util-to-html` (e.g., v8) that supports CommonJS. Ensure your `package.json` specifies `"type": "module"` for ESM.
```
TypeError: (0 , hast_util_to_html__WEBPACK_IMPORTED_MODULE_0__.toHtml) is not a function
```
cause Incorrect import syntax (e.g., trying to default import a named export) or a version mismatch where `toHtml` might not be directly available.

fix Ensure you are using named imports: `import { toHtml } from 'hast-util-to-html';`. Verify that `hast-util-to-html` is correctly installed and that the version is compatible with your code.
```
Property 'entities' does not exist on type 'Options'. Did you mean 'characterReferences'?
```
cause Using the deprecated `entities` option from v8 with `hast-util-to-html` v9 or newer.

fix Update your code to use the `characterReferences` option instead of `entities`. For example, `options: { characterReferences: { useNamedReferences: true } }`.

Warnings

breaking Version 9.0.0 changed to be ESM-only and requires Node.js 16 or higher. Projects still using CommonJS or older Node.js versions must stick to v8 or migrate.
Fix: Upgrade Node.js to 16+ and migrate imports to ESM syntax (e.g., `import` instead of `require`). If migration is not possible, use `hast-util-to-html@8`.
breaking The `entities` option was removed in v9.0.0 and replaced with `characterReferences`. Trying to use `options.entities` will result in a TypeScript error or runtime property access issues.
Fix: Replace `options.entities` with `options.characterReferences` and adjust its properties accordingly (e.g., `useNamedReferences`, `omitOptionalSemicolons`).
breaking Version 9.0.0 transitioned to Node.js `exports` field, which means internal or private APIs are no longer directly accessible. Relying on undocumented paths will break.
Fix: Only use publicly documented exports. Avoid deep imports into `node_modules/hast-util-to-html`.
gotcha Setting `allowDangerousCharacters` or `allowDangerousHtml` to `true` can introduce XSS vulnerabilities if the input HAST tree is not fully trusted. These options should only be used in controlled environments or with guaranteed safe input.
Fix: Ensure that `allowDangerousCharacters` and `allowDangerousHtml` are `false` (the default) unless you have thoroughly vetted the input source and understand the security implications. Sanitize or validate user-generated HAST trees before serialization.
gotcha The `characterReferences.omitOptionalSemicolons` option, when enabled, can produce HTML that causes 'parse errors' according to HTML specifications. While still technically valid, it is primarily intended for minification and might cause issues with some parsers or validators.
Fix: Only enable `characterReferences.omitOptionalSemicolons` if you are specifically building a minifier and have tested its compatibility with your target environment. For general use, keep this option disabled.

Install

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

Imports

toHtml
wrong:
```
const { toHtml } = require('hast-util-to-html');
```
correct:
```
import { toHtml } from 'hast-util-to-html';
```
The package is ESM-only since v9, so CommonJS `require` is not supported.
Options
```
import type { Options } from 'hast-util-to-html';
```
Type import for configuring serialization behavior; not a runtime value.
toHtml (Deno/Browser)
```
import {toHtml} from 'https://esm.sh/hast-util-to-html@9'
```
For Deno environments or browser consumption via `esm.sh`. Add `?bundle` for browser build.

Quickstart

This quickstart demonstrates creating a HAST tree and then serializing it into an HTML string using `toHtml` with default and custom options.

import {h} from 'hastscript';
import {toHtml} from 'hast-util-to-html';

// Create a HAST tree using hastscript for convenience
const tree = h('.alpha', [
  'bravo ',
  h('b', 'charlie'),
  ' delta ',
  h('a.echo', {download: true, href: '#'}, 'foxtrot')
]);

// Serialize the HAST tree to an HTML string with default options
console.log(toHtml(tree));

// Example with options: omit quotes for attributes where possible
console.log(toHtml(tree, { quote: false }));

view raw JSON →