{"id":11016,"library":"hast-util-to-html","title":"HAST to HTML Serializer","description":"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.","status":"active","version":"9.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-to-html","tags":["javascript","hast-util","hast","html","serialize","stringify","tostring","unist","utility","typescript"],"install":[{"cmd":"npm install hast-util-to-html","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-to-html","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-to-html","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for handling HTML property serialization, ensuring correct attribute output.","package":"property-information","optional":false}],"imports":[{"note":"The package is ESM-only since v9, so CommonJS `require` is not supported.","wrong":"const { toHtml } = require('hast-util-to-html');","symbol":"toHtml","correct":"import { toHtml } from 'hast-util-to-html';"},{"note":"Type import for configuring serialization behavior; not a runtime value.","symbol":"Options","correct":"import type { Options } from 'hast-util-to-html';"},{"note":"For Deno environments or browser consumption via `esm.sh`. Add `?bundle` for browser build.","symbol":"toHtml (Deno/Browser)","correct":"import {toHtml} from 'https://esm.sh/hast-util-to-html@9'"}],"quickstart":{"code":"import {h} from 'hastscript';\nimport {toHtml} from 'hast-util-to-html';\n\n// Create a HAST tree using hastscript for convenience\nconst tree = h('.alpha', [\n  'bravo ',\n  h('b', 'charlie'),\n  ' delta ',\n  h('a.echo', {download: true, href: '#'}, 'foxtrot')\n]);\n\n// Serialize the HAST tree to an HTML string with default options\nconsole.log(toHtml(tree));\n\n// Example with options: omit quotes for attributes where possible\nconsole.log(toHtml(tree, { quote: false }));","lang":"typescript","description":"This quickstart demonstrates creating a HAST tree and then serializing it into an HTML string using `toHtml` with default and custom options."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Replace `options.entities` with `options.characterReferences` and adjust its properties accordingly (e.g., `useNamedReferences`, `omitOptionalSemicolons`).","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Only use publicly documented exports. Avoid deep imports into `node_modules/hast-util-to-html`.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=9.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require()` an ESM-only package in a CommonJS context.","error":"ERR_REQUIRE_ESM"},{"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.","cause":"Incorrect import syntax (e.g., trying to default import a named export) or a version mismatch where `toHtml` might not be directly available.","error":"TypeError: (0 , hast_util_to_html__WEBPACK_IMPORTED_MODULE_0__.toHtml) is not a function"},{"fix":"Update your code to use the `characterReferences` option instead of `entities`. For example, `options: { characterReferences: { useNamedReferences: true } }`.","cause":"Using the deprecated `entities` option from v8 with `hast-util-to-html` v9 or newer.","error":"Property 'entities' does not exist on type 'Options'. Did you mean 'characterReferences'?"}],"ecosystem":"npm"}