html-to-text

html-to-text is a battle-tested Node.js library that parses HTML documents and renders them as clean, readable plain text. It handles the messy realities of real-world markup — inline and block-level tags, tables with colspans and rowspans, links with their hrefs, Unicode content, and word wrapping — so you never have to strip tags with brittle regular expressions again.

Beyond simple tag stripping, it exposes a stylesheet-like selector system that lets you decide exactly how each element is formatted, skipped, or transformed. With over 11 million weekly downloads, it is the de-facto standard for generating plain-text email bodies, previews, search indexes, and text snapshots from HTML.

What You Get

• A simple convert / htmlToText function plus a compile factory for reusing options across many documents at high throughput
• A stylesheet-like selector system to format, skip, or customize the rendering of any HTML element
• Built-in formatters for links, images, tables, ordered and unordered lists, headings, blockquotes, and horizontal rules
• Configurable word wrapping, long-word splitting, whitespace handling, and entity decoding
• Dual CommonJS and ES module builds with bundled TypeScript typedefs

Common Use Cases

• Generating plain-text alternatives for HTML emails so messages render in text-only clients
• Producing readable previews, excerpts, or notification snippets from stored HTML content
• Feeding clean text into full-text search indexes or analytics pipelines
• Creating deterministic text snapshots of rendered HTML for testing

Under The Hood

Architecture The project is a pnpm-style monorepo whose published html-to-text package sits on top of a shared base package. A call to convert first composes user options with the defaults via options-composer, then parses the HTML string with htmlparser2 into a DOM. Element formatting decisions come from the selectors array, which selderee/parseley compile into an efficient decision tree so each DOM node is matched against selectors in near-constant time rather than being tested one-by-one. Matched nodes are dispatched to formatters (in text-formatters.js, table-printer.js, and the base package’s generic formatters) that push content into a BlockTextBuilder; that builder — together with InlineTextBuilder and whitespace-processor — handles block spacing, inline concatenation, whitespace collapsing, and word wrapping to assemble the final string.

Tech Stack Written in modern JavaScript (ES2022, ESM-first) targeting Node.js >= 20.19. Runtime dependencies are minimal and focused: htmlparser2 for HTML parsing, dom-serializer for serialization, selderee with @selderee/plugin-htmlparser2 for selector compilation, and deepmerge-ts for options merging. The package ships dual CJS/ESM bundles produced by Rollup; tests run on AVA with c8 for coverage, and linting is handled by ESLint.

Code Quality The codebase is small, modular, and well-tested. The html-to-text package alone carries roughly two dozen AVA test files spread across general behavior, individual tag handling, and full-document snapshot fixtures. Source files are concise (the core is around 200 lines), documented with JSDoc typedefs, and cleanly separate parsing, selector matching, and text building into distinct modules. Options are validated and merged predictably, and the extensive CHANGELOG documents deprecations across major versions.

API Design The public surface is deliberately tiny — convert, its htmlToText alias, and compile — which makes the common case trivial while the selector and custom-formatter systems provide deep escape hatches for advanced needs. The 22 KB README documents every option, selector, and predefined formatter with runnable examples, and the compile pattern gives a clear, well-signposted path to high performance when processing batches. Naming is consistent and the migration notes between major versions are thorough.