HAST Node Plain-Text Converter

3.0.1 · active · verified Sun Apr 19

hast-util-to-string is a utility within the `unified` ecosystem designed to extract the plain-text value of a `hast` (HTML Abstract Syntax Tree) node. It strictly mimics the DOM's `Node#textContent` getter, returning all textual content regardless of styling or layout, and importantly, it does not interpret HTML elements like `<br>` as introducing newlines. This behavior differentiates it from `hast-util-to-text`, which emulates `Node#innerText` by considering rendered output. The current stable version is 3.0.1. As part of the actively maintained `unified` collective, it follows a release cadence tied to the broader ecosystem, with major versions often introducing updated Node.js requirements (e.g., Node.js 16+ for v3) and migrating to modern JavaScript module practices, including being ESM-only and utilizing package `exports` fields. The library provides comprehensive TypeScript type definitions, ensuring robust development.

Common errors

```
ERR_REQUIRE_ESM: require() of ES Module .../node_modules/hast-util-to-string/index.js from ... not supported.
```
cause Attempting to use CommonJS `require()` to import `hast-util-to-string`, which is an ESM-only package.

fix Change `const { toString } = require('hast-util-to-string')` to `import { toString } from 'hast-util-to-string'`. Ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json`).
```
TypeError: (0, hast_util_to_string_1.toString) is not a function
```
cause This error often occurs when trying to use a default import for `toString`, but `hast-util-to-string` provides `toString` as a named export.

fix Ensure you are using a named import: `import { toString } from 'hast-util-to-string'` instead of `import toString from 'hast-util-to-string'`.

Warnings

breaking `hast-util-to-string` v3 and newer packages in the `unified` ecosystem are ESM-only, requiring projects to adopt ES module syntax (`import`/`export`) and tooling. CommonJS `require()` is no longer supported.
Fix: Migrate your project to use ES module syntax. For Node.js, ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions. Update bundler configurations if applicable.
breaking Version 3.0.0 and subsequent releases require Node.js 16 or higher. Older Node.js versions are not supported.
Fix: Upgrade your Node.js environment to version 16 or newer. Use `nvm` or other version managers for easier switching.
gotcha `hast-util-to-string` implements the `Node#textContent` algorithm, which extracts text content without regard for HTML display properties (e.g., `<br>` does not introduce a newline). If you need `Node#innerText`-like behavior (which considers rendered layout), use `hast-util-to-text` instead.
Fix: If line breaks or other layout-aware text extraction is needed, switch to `hast-util-to-text`. Otherwise, ensure your code accounts for `textContent` behavior.
gotcha The `unified` ecosystem, including `hast-util-to-string`, processes HTML. Improper use or failure to sanitize input/output can lead to Cross-Site Scripting (XSS) vulnerabilities. This package itself does not sanitize content.
Fix: Always use a sanitizer like `rehype-sanitize` on `hast` trees before serializing them back to HTML, especially when dealing with untrusted user input.

Install

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

Imports

toString
wrong:
```
import toString from 'hast-util-to-string'
```
correct:
```
import { toString } from 'hast-util-to-string'
```
The `toString` function is a named export, not a default export. This package is ESM-only since v3.
toString
wrong:
```
const toString = require('hast-util-to-string')
```
correct:
```
import { toString } from 'hast-util-to-string'
```
This package is ESM-only and requires Node.js 16+ for v3 and newer. CommonJS `require()` is not supported directly.
toString
```
import {toString} from 'https://esm.sh/hast-util-to-string@3'
```
For browser or Deno environments, it can be imported directly from a CDN like esm.sh, specifying the version.

Quickstart

This quickstart demonstrates how to convert both simple and complex HAST nodes into their plain-text representations using `hast-util-to-string`, highlighting its `Node#textContent`-like behavior.

import {h, type Element} from 'hastscript';
import {toString} from 'hast-util-to-string';

// Create a simple HAST paragraph node
const paragraphNode: Element = h('p', 'This is a simple paragraph.');
console.log('Input HAST node (paragraph):', JSON.stringify(paragraphNode, null, 2));
console.log('Plain text output:', toString(paragraphNode));
// Expected output: 'This is a simple paragraph.'

// Create a more complex HAST div node with nested elements and a break tag
const complexNode: Element = h('div', [
  h('b', 'Bold text'),
  ' and ', 
  h('i', 'italic text'),
  h('br'), // A break tag
  ' on the same line according to textContent (no newline).' // textContent doesn't add newline for <br>
]);
console.log('\nInput HAST node (complex div):', JSON.stringify(complexNode, null, 2));
console.log('Plain text output:', toString(complexNode));
// Expected output: 'Bold text and italic text. on the same line according to textContent (no newline).'
// This demonstrates that <br> tags are ignored when mimicking Node#textContent behavior.

view raw JSON →