HAST Plain-Text Extraction

4.0.2 · active · verified Sun Apr 19

hast-util-to-text is a utility for the unified ecosystem that extracts the plain-text value from a HAST (HTML Abstract Syntax Tree) node. It approximates the DOM's `Node#innerText` algorithm, which is more user-friendly than `Node#textContent` (like `hast-util-to-string`) by converting `<br>` elements into line breaks and using tabs (`\t`) between table cells. The package is currently at version 4.0.2, actively maintained, and primarily releases patch versions for fixes and minor updates for new features, with major versions reserved for breaking changes. Its key differentiator is its adherence to the `innerText`-like behavior, providing a textual representation that reflects how content would be visually rendered, although it cannot account for dynamic CSS properties like `display: none` or `text-transform`.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` an ESM-only package.

fix Change `const { toText } = require('hast-util-to-text')` to `import { toText } from 'hast-util-to-text'`.
```
TypeError: toText is not a function
```
cause Incorrect import syntax (e.g., default import when only named exports exist, or attempting to destructure from an incorrectly transpiled CJS module).

fix Ensure you are using named imports: `import { toText } from 'hast-util-to-text'`.
```
Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package 'hast-util-to-text' was not found at package.json#exports.
```
cause Using an older Node.js version (<16) that doesn't fully support the `exports` field in `package.json`, or an outdated bundler/tooling.

fix Update Node.js to version 16 or newer. Ensure your build tooling (e.g., webpack, Rollup, Parcel) is up-to-date and configured to handle ESM and `exports` maps correctly.

Warnings

breaking Version 4.0.0 changed 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. Use `nvm install 16` or update your CI/CD configuration.
breaking Version 4.0.0 changed the package to use the `exports` field in `package.json`, which affects how it can be imported, particularly in CommonJS environments or older bundlers. It's designed for modern ESM import patterns.
Fix: Ensure your build tooling and Node.js version support the `exports` field. Always use `import` statements for ESM modules. Avoid using private APIs if previously done.
breaking Version 3.0.0 converted the package to be ESM-only. CommonJS `require()` statements will no longer work.
Fix: Migrate your codebase to use ES Modules (`import ... from '...'`) for this package. If you must use CommonJS, consider transpiling your code or sticking to an older major version (e.g., `<3.0.0`).
breaking Version 2.0.0 updated `unist-util-find-after`, which could be a breaking change, particularly for TypeScript users or dependents relying on specific type definitions.
Fix: Review the changelog for `unist-util-find-after` and `hast-util-to-text` v2.0.0. Update `@types/unist` and related packages to ensure type compatibility.
gotcha This utility's `innerText` algorithm is an approximation and deviates from the DOM specification in some cases. It cannot account for CSS properties like `display: none` or `text-transform` that dynamically alter text visibility or appearance, nor does it process replaced elements (e.g., `<audio>`) as the DOM would.
Fix: Be aware of these limitations. If exact DOM `innerText` behavior is required, consider using a headless browser environment (e.g., Puppeteer, JSDOM) to render and extract text, as `hast-util-to-text` cannot interpret CSS.

Install

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

Imports

toText
wrong:
```
const toText = require('hast-util-to-text')
```
correct:
```
import { toText } from 'hast-util-to-text'
```
This package is ESM-only since v3.0.0. CommonJS `require()` is not supported. It also requires Node.js 16+ since v4.0.0.
Options
```
import type { Options } from 'hast-util-to-text'
```
Type import for configuring the `toText` function, for use in TypeScript projects. It's a type, so it uses `import type`.
Whitespace
```
import type { Whitespace } from 'hast-util-to-text'
```
Type import for the `whitespace` option, specifying how whitespace should be handled. For use in TypeScript projects.

Quickstart

This quickstart demonstrates how to use `toText` to convert a HAST tree into a plain-text string, showing how it handles line breaks from `<br>` and tabs in table cells.

import {h} from 'hastscript'
import {toText} from 'hast-util-to-text'

const tree = h('div', [
  h('h1', {hidden: true}, 'Alpha.'),
  h('article', [
    h('p', ['Bravo', h('br'), 'charlie.']), // <br> will become a newline
    h('p', 'Delta echo \t foxtrot.') // Tab will be preserved
  ]),
  h('table', [
    h('tr', [
      h('td', 'Cell 1'),
      h('td', 'Cell 2')
    ])
  ])
])

console.log(toText(tree));
// Expected output:
// Bravo
// charlie.
//
// Delta echo    foxtrot.
// Cell 1    Cell 2

view raw JSON →