{"id":10998,"library":"hast-util-from-html","title":"HAST Utility for Parsing HTML","description":"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.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-from-html","tags":["javascript","unist","hast","hast-util","util","utility","html","parse","tokenize","typescript"],"install":[{"cmd":"npm install hast-util-from-html","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-from-html","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-from-html","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only since v2.0.0; Node.js 16+ is required. CommonJS `require` is not supported for direct imports.","wrong":"const { fromHtml } = require('hast-util-from-html')","symbol":"fromHtml","correct":"import { fromHtml } from 'hast-util-from-html'"},{"note":"This is a TypeScript type, defining known parse error codes. For JavaScript users, it's not directly imported but describes values used in options.","symbol":"ErrorCode","correct":"import type { ErrorCode } from 'hast-util-from-html'"},{"note":"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.","symbol":"Options","correct":"import type { Options } from 'hast-util-from-html'"}],"quickstart":{"code":"import { fromHtml } from 'hast-util-from-html';\nimport type { Root } from 'hast';\n\nconst htmlInput = '

Hello, world!

This is a paragraph.

';\n\n// Parse as a document fragment to avoid automatic , , insertion.\nconst tree: Root = fromHtml(htmlInput, { fragment: true });\n\nconsole.log(JSON.stringify(tree, null, 2));\n\n// Example of parsing as a full document\nconst documentHtml = 'Test

Doc

';\nconst docTree: Root = fromHtml(documentHtml);\nconsole.log('\\n--- Full Document Parse ---\\n');\nconsole.log(JSON.stringify(docTree, null, 2));","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer.","message":"Version 2.0.0 and above require Node.js 16 or higher. Using older Node.js versions will result in runtime errors.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Only use the public API as exported from the main package entry point (`import { ... } from 'hast-util-from-html'`).","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For parsing HTML fragments, use `fromHtml(value, { fragment: true })`.","message":"By default, `fromHtml` parses input as a complete HTML document, potentially inserting ``, ``, and `` elements around your input. If you intend to parse only a snippet, use the `fragment: true` option.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the API documentation for `OnError`, `ErrorCode`, and `ErrorSeverity` to customize how parse errors are reported or handled via the `onerror` option.","message":"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.","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":"Switch to ES module `import` syntax: `import { fromHtml } from 'hast-util-from-html'` and ensure your project is configured to run ESM.","cause":"Attempting to `require()` `hast-util-from-html` in a CommonJS environment, which is an ESM-only package since v2.0.0.","error":"ERR_REQUIRE_ESM"},{"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.","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.","error":"SyntaxError: Named export 'fromHtml' not found. The requested module 'hast-util-from-html' does not provide an export named 'fromHtml'"},{"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.","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).","error":"TypeError: fromHtml is not a function"}],"ecosystem":"npm"}