html-react-parser

html-react-parser is a lightweight TypeScript library that converts raw HTML strings into React elements at runtime. It runs identically in Node.js (SSR) and in the browser, making it useful anywhere HTML content needs to be rendered as native React nodes rather than injected via dangerouslySetInnerHTML.

The library exposes a single default-export function alongside a replace option for swapping specific DOM elements with custom React components, and a transform option for per-node transformation during traversal. It builds on html-dom-parser (a wrapper around htmlparser2) for parsing and style-to-js for inline style conversion, keeping the dependency surface small while supporting custom parsing engines.

What You Get

• A single parse(html, options) function that returns React elements, an array of elements, or a string
• A replace option to swap matched DOM nodes with custom React components or remove them
• A transform option for per-node transformation during the HTML-to-React walk
• Works identically during server-side rendering and in the browser
• TypeScript types shipped in the package, plus CJS, ESM, and UMD builds

Common Use Cases

• Rendering HTML fetched from a headless CMS as native React elements instead of raw innerHTML
• Replacing specific tags (e.g. <a>, <img>) with custom React components while parsing rich content
• Server-rendering HTML fragments in a Next.js or other SSR app without a client-only DOM dependency
• Post-processing markdown-rendered HTML to inject interactive React components

Under The Hood

Architecture The library is a thin three-stage pipeline: html-dom-parser (an htmlparser2 wrapper) parses the input HTML string into a DOM node tree, dom-to-react.ts recursively walks that tree converting each DOMNode into React.createElement calls (handling replace/transform hooks per node), and attributes-to-props.ts maps HTML attributes/inline styles to React props (via style-to-js and react-property for attribute-name mapping). The public surface is a single default export (src/index.ts, 40 lines) that wires these stages together, keeping the whole conversion synchronous and dependency-light.

Tech Stack Written in TypeScript, built with tsc for CJS and Rollup for a UMD bundle, targeting both CJS and ESM consumers via package.json exports. Runtime dependencies are minimal and pinned exactly: domhandler, html-dom-parser, react-property, style-to-js. Tests run on Vitest (including a browser mode via Playwright for real-DOM verification), linting via ESLint 10 with typescript-eslint, and releases are automated with conventional commits and changelog generation.

Code Quality The __tests__ directory mirrors src/ one-to-one (dom-to-react, attributes-to-props, utilities.test.ts, plus an integration/ suite and browser-mode tests), and CI runs both Node and browser test targets plus arethetypeswrong and publint to verify package exports are correct. Source files are small and single-purpose (40-182 lines each), fully typed with exported HTMLReactParserOptions, and the entry point throws a TypeError on non-string input rather than failing silently.

API Design The API is a single default function with an optional second options argument, so the zero-config path (parse(html)) requires no setup. Power users get two well-documented escape hatches (replace, transform) without needing to learn a plugin system, and the package re-exports the underlying DOM node types (Comment, Element, Text) so consumers can type-narrow inside replace callbacks. The extensive README with a table of contents, FAQ, and migration guides for five major versions materially lowers the learning curve.