Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Parser
✓ import { Parser } from 'html-to-react';
✗ const HtmlToReactParser = require('html-to-react').Parser;
For ESM environments, use a named import. Older CommonJS examples frequently use `require` to access the `Parser` property of the module's export.
ProcessNodeDefinitions
✓ import { ProcessNodeDefinitions } from 'html-to-react';
✗ const HtmlToReact = require('html-to-react'); const processNodeDefinitions = new HtmlToReact.ProcessNodeDefinitions();
In ESM, `ProcessNodeDefinitions` is directly available as a named import. In CommonJS, it's typically accessed as a property of the main module export object after requiring the package.
Type Imports
✓ import type { HtmlToReactParser, ProcessingInstruction, CustomisableNode } from 'html-to-react';
For TypeScript projects, specific interfaces and types like `HtmlToReactParser`, `ProcessingInstruction`, or `CustomisableNode` can be imported using type-only imports.
This example demonstrates how to parse an HTML string, apply custom processing instructions (specifically capitalizing the content of H1 tags), and then render the resulting React component tree back to a static HTML string. It highlights the use of `Parser` and `ProcessNodeDefinitions` with TypeScript typings.
import React from 'react';
import ReactDOMServer from 'react-dom/server';
import { Parser, ProcessNodeDefinitions } from 'html-to-react';
interface CustomNode extends Node {
data?: string;
name?: string;
parent?: CustomNode; // Add parent for 'shouldProcessNode' logic
}
const htmlInput = '<div><h1>Title</h1><p>Paragraph</p><h1>Another title</h1></div>';
const htmlExpected = '<div><h1>TITLE</h1><p>Paragraph</p><h1>ANOTHER TITLE</h1></div>';
// A function to determine if a node should be processed
const isValidNode = (node: CustomNode) => true;
// Order of instructions matters: most specific to most general
const processNodeDefinitions = new ProcessNodeDefinitions();
const processingInstructions = [
{
// Custom processing for <h1> tags: capitalize their content
shouldProcessNode: (node: CustomNode) => {
// Check if the node is a child of an <h1> tag and contains text data
return node.parent && node.parent.name === 'h1' && node.type === 'text';
},
processNode: (node: CustomNode) => {
return node.data?.toUpperCase();
}
},
{
// Default processing for all other nodes that haven't been handled
shouldProcessNode: (node: CustomNode) => true,
processNode: processNodeDefinitions.processDefaultNode
}
];
const htmlToReactParser = new Parser();
const reactComponent = htmlToReactParser.parseWithInstructions(
htmlInput,
isValidNode,
processingInstructions
);
// Render the resulting React component tree back to static HTML
const reactHtml = ReactDOMServer.renderToStaticMarkup(reactComponent);
console.log('Original HTML Input:', htmlInput);
console.log('Processed React HTML Output:', reactHtml);
console.log('Assertion (output matches expected):', reactHtml === htmlExpected);
Debug
Known issues
breakingThe library has very old React peer dependencies (`^0.13.0 || ^0.14.0 || >=15`) and has not been updated in over six years. It is highly unlikely to work without issues with modern React versions (e.g., React 17+ or 18+) due to significant changes in React's internal mechanisms, context API, and rendering lifecycle.fixConsider alternative, actively maintained HTML-to-React libraries (e.g., `html-react-parser`, `react-html-parser`) for modern React applications, or fork and adapt the library if its specific functionality is critical and compatibility issues can be resolved.
affects: >=1.0.0 (all versions when used with modern React)
gotchaThe order of `processingInstructions` is critical. Instructions are executed sequentially, and the first `shouldProcessNode` that returns `true` for a given node will have its `processNode` method applied. Subsequent instructions for that node will be ignored.fixCarefully arrange processing instructions from most specific to most general. Ensure a broad catch-all instruction (e.g., `shouldProcessNode: () => true`) is placed last if default processing is desired for unhandled nodes.
affects: >=1.0.0
gotchaDirectly rendering arbitrary user-supplied HTML content can lead to Cross-Site Scripting (XSS) vulnerabilities. While `html-to-react` converts to React elements, it does not inherently sanitize or filter malicious scripts within the HTML input.fixAlways sanitize HTML input from untrusted sources *before* passing it to `html-to-react`. Use a dedicated HTML sanitization library (e.g., `dompurify`) to strip potentially harmful tags and attributes.
affects: >=1.0.0
deprecatedThe library's primary examples and age reflect a reliance on CommonJS `require()` syntax. While CommonJS may still function in some environments, modern JavaScript projects typically utilize ESM `import` statements, which are not directly demonstrated in the original documentation.fixPrefer `import { Parser, ProcessNodeDefinitions } from 'html-to-react';` for ESM compatibility. Configure build tools (e.g., Webpack, Rollup) or Node.js environment to handle ESM. affects: <1.7.0 (examples), >=1.7.0 (modern contexts)
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'Parser') or (reading 'ProcessNodeDefinitions')
This error typically occurs when named exports (`Parser`, `ProcessNodeDefinitions`) are not correctly imported from the `html-to-react` module, or when attempting to use CommonJS `require` syntax in an ESM-only environment without proper transpilation.
fixEnsure you are using `import { Parser, ProcessNodeDefinitions } from 'html-to-react';` for ESM. Verify the package is installed and accessible in your `node_modules`. Error: Invariant Violation: Minified React error #XXX; visit https://reactjs.org/docs/error-decoder.html?invariant=XXX for the full message or use the non-minified dev environment for full errors.
This generic React invariant violation often indicates a compatibility issue with the React version being used, rendering invalid React elements, or internal inconsistencies due to the `html-to-react` library's old peer dependencies conflicting with modern React's core mechanisms.
fixVerify that the `react` version installed in your project aligns with the range specified by `html-to-react`'s peer dependencies. For modern React applications, it's strongly recommended to use a different, actively maintained HTML-to-React parsing library.
Audit
Dependencies
reactrequiredRequired as a peer dependency for creating and rendering React elements. The library's core functionality relies on React's component model and element creation. The specified peer dependency versions are quite old, indicating potential compatibility issues with modern React.