Gathering detailed insights and metrics for html-react-parser
Gathering detailed insights and metrics for html-react-parser
Installations
npm install html-react-parserDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS, ESM
Node Version
22.15.0
NPM Version
10.9.2
Score
97.1
Supply Chain
99.2
Quality
87
Maintenance
100
Vulnerability
100
License
Releases
151
Languages
2
TypeScript
JavaScript
TypeScript (88.78%)
JavaScript (11.22%)
Developer
Download Statistics
Total Downloads
233,649,795
Last Day
58,016
Last Week
1,828,047
Last Month
7,933,102
Last Year
81,419,309
GitHub Statistics
MIT License
2,306 Stars
2,972 Commits
134 Forks
7 Watchers
4 Branches
33 Contributors
Updated on Jul 03, 2025
Bundle Size
28.62 kB
Minified
9.65 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
5.2.5
Package Id
html-react-parser@5.2.5
Unpacked Size
457.27 kB
Size
113.98 kB
File Count
40
NPM Version
10.9.2
Node Version
22.15.0
Published on
May 12, 2025
Total Downloads
Cumulative downloads
Total Downloads
233,649,795
Last Day
2%
58,016
Compared to previous day
Last Week
-7.5%
1,828,047
Compared to previous week
Last Month
0.6%
7,933,102
Compared to previous month
Last Year
32.8%
81,419,309
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
4
Peer Dependencies
2
Dev Dependencies
35
@commitlint/cli@commitlint/config-conventional@eslint/compat@eslint/eslintrc@eslint/js@rollup/plugin-commonjs@rollup/plugin-node-resolve@rollup/plugin-terser@rollup/plugin-typescript@size-limit/preset-big-lib@types/benchmark@types/jest@types/node@types/react@types/react-dom@typescript-eslint/eslint-plugin@typescript-eslint/parserbenchmarkeslinteslint-plugin-prettiereslint-plugin-simple-import-sortglobalshuskyjestjest-environment-jsdomjest-watch-typeaheadlint-stagedpreactreactreact-domrollupsize-limitts-jestts-nodetypescript
html-react-parser
HTML to React parser that works on both the server (Node.js) and the client (browser):
HTMLReactParser(string[, options])
The parser converts an HTML string to one or more React elements.
To replace an element with another element, check out the replace option.
Example
1import parse from 'html-react-parser'; 2 3parse('<p>Hello, World!</p>'); // React.createElement('p', {}, 'Hello, World!')
Replit | JSFiddle | StackBlitz | TypeScript | Examples
Table of Contents
- Install
- Usage
- Migration
- FAQ
- Is this XSS safe?
- Does invalid HTML get sanitized?
- Are
<script>tags parsed? - Attributes aren't getting called
- Parser throws an error
- Is SSR supported?
- Elements aren't nested correctly
- Don't change case of tags
- TS Error: Property 'attribs' does not exist on type 'DOMNode'
- Can I enable
trimfor certain elements? - Webpack build warnings
- TypeScript error
- Performance
- Contributors
- Support
- License
Install
NPM:
1npm install html-react-parser --save
Yarn:
1yarn add html-react-parser
CDN:
1<!-- HTMLReactParser depends on React --> 2<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script> 3<script src="https://unpkg.com/html-react-parser@latest/dist/html-react-parser.min.js"></script> 4<script> 5 window.HTMLReactParser(/* string */); 6</script>
Usage
Import ES module:
1import parse from 'html-react-parser';
Or require CommonJS module:
1const parse = require('html-react-parser').default;
Parse single element:
1parse('<h1>single</h1>');
Parse multiple elements:
1parse('<li>Item 1</li><li>Item 2</li>');
Make sure to render parsed adjacent elements under a parent element:
1<ul> 2 {parse(` 3 <li>Item 1</li> 4 <li>Item 2</li> 5 `)} 6</ul>
Parse nested elements:
1parse('<body><p>Lorem ipsum</p></body>');
Parse element with attributes:
1parse( 2 '<hr id="foo" class="bar" data-attr="baz" custom="qux" style="top:42px;">', 3);
replace
The replace option allows you to replace an element with another element.
The replace callback's first argument is domhandler's node:
1parse('<br>', { 2 replace(domNode) { 3 console.dir(domNode, { depth: null }); 4 }, 5});
Console output
1Element { 2 type: 'tag', 3 parent: null, 4 prev: null, 5 next: null, 6 startIndex: null, 7 endIndex: null, 8 children: [], 9 name: 'br', 10 attribs: {} 11}
The element is replaced if a valid React element is returned:
1parse('<p id="replace">text</p>', { 2 replace(domNode) { 3 if (domNode.attribs && domNode.attribs.id === 'replace') { 4 return <span>replaced</span>; 5 } 6 }, 7});
The second argument is the index:
1parse('<br>', { 2 replace(domNode, index) { 3 console.assert(typeof index === 'number'); 4 }, 5});
[!NOTE] The index will restart at 0 when traversing the node's children so don't rely on index being a unique key. See #1259.
replace with TypeScript
You need to check that domNode is an instance of domhandler's Element:
1import { HTMLReactParserOptions, Element } from 'html-react-parser'; 2 3const options: HTMLReactParserOptions = { 4 replace(domNode) { 5 if (domNode instanceof Element && domNode.attribs) { 6 // ... 7 } 8 }, 9};
Or use a type assertion:
1import { HTMLReactParserOptions, Element } from 'html-react-parser'; 2 3const options: HTMLReactParserOptions = { 4 replace(domNode) { 5 if ((domNode as Element).attribs) { 6 // ... 7 } 8 }, 9};
If you're having issues, take a look at our Create React App example.
replace element and children
Replace the element and its children (see demo):
1import parse, { domToReact } from 'html-react-parser'; 2 3const html = ` 4 <p id="main"> 5 <span class="prettify"> 6 keep me and make me pretty! 7 </span> 8 </p> 9`; 10 11const options = { 12 replace({ attribs, children }) { 13 if (!attribs) { 14 return; 15 } 16 17 if (attribs.id === 'main') { 18 return <h1 style={{ fontSize: 42 }}>{domToReact(children, options)}</h1>; 19 } 20 21 if (attribs.class === 'prettify') { 22 return ( 23 <span style={{ color: 'hotpink' }}> 24 {domToReact(children, options)} 25 </span> 26 ); 27 } 28 }, 29}; 30 31parse(html, options);
HTML output
1<h1 style="font-size:42px"> 2 <span style="color:hotpink"> 3 keep me and make me pretty! 4 </span> 5</h1>
replace element attributes
Convert DOM attributes to React props with attributesToProps:
1import parse, { attributesToProps } from 'html-react-parser'; 2 3const html = ` 4 <main class="prettify" style="background: #fff; text-align: center;" /> 5`; 6 7const options = { 8 replace(domNode) { 9 if (domNode.attribs && domNode.name === 'main') { 10 const props = attributesToProps(domNode.attribs); 11 return <div {...props} />; 12 } 13 }, 14}; 15 16parse(html, options);
HTML output
1<div class="prettify" style="background:#fff;text-align:center"></div>
replace and remove element
Exclude an element from rendering by replacing it with <React.Fragment>:
1parse('<p><br id="remove"></p>', { 2 replace: ({ attribs }) => attribs?.id === 'remove' && <></>, 3});
HTML output
1<p></p>
transform
The transform option allows you to transform each element individually after it's parsed.
The transform callback's first argument is the React element:
1parse('<br>', { 2 transform(reactNode, domNode, index) { 3 // this will wrap every element in a div 4 return <div>{reactNode}</div>; 5 }, 6});
library
The library option specifies the UI library. The default library is React.
To use Preact:
1parse('<br>', { 2 library: require('preact'), 3});
Or a custom library:
1parse('<br>', { 2 library: { 3 cloneElement: () => { 4 /* ... */ 5 }, 6 createElement: () => { 7 /* ... */ 8 }, 9 isValidElement: () => { 10 /* ... */ 11 }, 12 }, 13});
htmlparser2
[!WARNING]
htmlparser2options don't work on the client-side (browser); they only work on the server-side (Node.js). By overriding the options, it can break universal rendering.
Default htmlparser2 options can be overridden in >=0.12.0.
To enable xmlMode:
1parse('<p /><p />', { 2 htmlparser2: { 3 xmlMode: true, 4 }, 5});
trim
By default, whitespace is preserved:
1parse('<br>\n'); // [React.createElement('br'), '\n']
But certain elements like <table> will strip out invalid whitespace:
1parse('<table>\n</table>'); // React.createElement('table')
To remove whitespace, enable the trim option:
1parse('<br>\n', { trim: true }); // React.createElement('br')
However, intentional whitespace may be stripped out:
1parse('<p> </p>', { trim: true }); // React.createElement('p')
Migration
v5
Migrated to TypeScript. CommonJS imports require the .default key:
1const parse = require('html-react-parser').default;
If you're getting the error:
Argument of type 'ChildNode[]' is not assignable to parameter of type 'DOMNode[]'.
Then use type assertion:
1domToReact(domNode.children as DOMNode[], options);See #1126.
v4
htmlparser2 has been upgraded to v9.
v3
domhandler has been upgraded to v5 so some parser options like normalizeWhitespace have been removed.
Also, it's recommended to upgrade to the latest version of TypeScript.
v2
Since v2.0.0, Internet Explorer (IE) is no longer supported.
v1
TypeScript projects will need to update the types in v1.0.0.
For the replace option, you may need to do the following:
1import { Element } from 'domhandler/lib/node'; 2 3parse('<br class="remove">', { 4 replace(domNode) { 5 if (domNode instanceof Element && domNode.attribs.class === 'remove') { 6 return <></>; 7 } 8 }, 9});
Since v1.1.1, Internet Explorer 9 (IE9) is no longer supported.
FAQ
Is this XSS safe?
No, this library is not XSS (cross-site scripting) safe. See #94.
Does invalid HTML get sanitized?
No, this library does not sanitize HTML. See #124, #125, and #141.
Are <script> tags parsed?
Although <script> tags and their contents are rendered on the server-side, they're not evaluated on the client-side. See #98.
Attributes aren't getting called
The reason why your HTML attributes aren't getting called is because inline event handlers (e.g., onclick) are parsed as a string rather than a function. See #73.
Parser throws an error
If the parser throws an error, check if your arguments are valid. See "Does invalid HTML get sanitized?".
Is SSR supported?
Yes, server-side rendering on Node.js is supported by this library. See demo.
Elements aren't nested correctly
If your elements are nested incorrectly, check to make sure your HTML markup is valid. The HTML to DOM parsing will be affected if you're using self-closing syntax (/>) on non-void elements:
1parse('<div /><div />'); // returns single element instead of array of elements
See #158.
Don't change case of tags
Tags are lowercased by default. To prevent that from happening, pass the htmlparser2 option:
1const options = { 2 htmlparser2: { 3 lowerCaseTags: false, 4 }, 5}; 6parse('<CustomElement>', options); // React.createElement('CustomElement')
[!WARNING] By preserving case-sensitivity of the tags, you may get rendering warnings like:
Warning: <CustomElement> is using incorrect casing. Use PascalCase for React components, or lowercase for HTML elements.
TS Error: Property 'attribs' does not exist on type 'DOMNode'
The TypeScript error occurs because DOMNode needs to be an instance of domhandler's Element. See migration or #199.
Can I enable trim for certain elements?
Yes, you can enable or disable trim for certain elements using the replace option. See #205.
Webpack build warnings
If you see the Webpack build warning:
export 'default' (imported as 'parse') was not found in 'html-react-parser'
Then update your Webpack config to:
1// webpack.config.js 2module.exports = { 3 // ... 4 resolve: { 5 mainFields: ['browser', 'main', 'module'], 6 }, 7};
TypeScript error
If you see the TypeScript error:
node_modules/htmlparser2/lib/index.d.ts:2:23 - error TS1005: ',' expected.
2 export { Parser, type ParserOptions };
~~~~~~~~~~~~~
Then upgrade to the latest version of typescript. See #748.
Performance
Run benchmark:
1npm run benchmark
Output of benchmark run on MacBook Pro 2021:
html-to-react - Single x 1,018,239 ops/sec ±0.43% (94 runs sampled)
html-to-react - Multiple x 380,037 ops/sec ±0.61% (97 runs sampled)
html-to-react - Complex x 35,091 ops/sec ±0.50% (96 runs sampled)
Run Size Limit:
1npx size-limit
Contributors
Code Contributors
This project exists thanks to all the people who contribute. [Contribute].
Financial Contributors
Become a financial contributor and help us sustain our community. [Contribute]
Individuals
Organizations
Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]
Support
License
No vulnerabilities found.
Reason
security policy file detected
Details
- Info: security policy file detected: .github/SECURITY.md:1
- Info: Found linked content: .github/SECURITY.md:1
- Info: Found disclosure, vulnerability, and/or timelines in security policy: .github/SECURITY.md:1
- Info: Found text in security policy: .github/SECURITY.md:1
Reason
update tool detected
Details
- Info: detected update tool: Dependabot: .github/dependabot.yml:1
Reason
no dangerous workflow patterns detected
Reason
30 commit(s) and 3 issue activity found in the last 90 days -- score normalized to 10
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
packaging workflow detected
Details
- Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release-please.yml:23
Reason
SAST tool is run on all commits
Details
- Info: all commits (30) are checked with a SAST tool
Reason
30 out of 30 merged PRs checked by a CI test -- score normalized to 10
Reason
project has 17 contributing companies or organizations
Details
- Info: found contributions from: HackTheDeep, VidhuCraft, ai-action, aovim, bgzt, bitly-community, braze-community, corsmirror, encrypit, getvinch, klaviyo, lilboards, lit-io, onyxinsight, remarkablegames, silentsolutionsdigital, ☁️
Reason
6 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
- Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
- Warn: Project is vulnerable to: GHSA-pq67-2wwv-3xjx
- Warn: Project is vulnerable to: GHSA-8cj5-5rvv-wf4v
- Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
Reason
dependency not pinned by hash detected -- score normalized to 3
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/build.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/build.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/build.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/build.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/commitlint.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/commitlint.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/commitlint.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/commitlint.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-please.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/release-please.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-please.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/release-please.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-please.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/release-please.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/scorecard.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/scorecard.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/scorecard.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:55: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/scorecard.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:64: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/scorecard.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/size-limit.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/size-limit.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/size-limit.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/remarkablemark/html-react-parser/size-limit.yml/master?enable=pin
- Info: 0 out of 10 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 4 third-party GitHubAction dependencies pinned
- Info: 3 out of 3 npmCommand dependencies pinned
Reason
branch protection is not maximal on development and all release branches
Details
- Info: 'allow deletion' disabled on branch 'master'
- Info: 'force pushes' disabled on branch 'master'
- Warn: 'branch protection settings apply to administrators' is disabled on branch 'master'
- Info: 'stale review dismissal' is required to merge on branch 'master'
- Warn: branch 'master' does not require approvers
- Warn: codeowners review is not required on branch 'master'
- Warn: 'last push approval' is disabled on branch 'master'
- Warn: 'up-to-date branches' is disabled on branch 'master'
- Info: status check found to merge onto on branch 'master'
- Info: PRs are required in order to make changes on branch 'master'
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release-please.yml:11
- Info: jobLevel 'contents' permission set to 'read': .github/workflows/release-please.yml:28
- Warn: no topLevel permission defined: .github/workflows/assign-reviewer.yml:1
- Warn: no topLevel permission defined: .github/workflows/build.yml:1
- Warn: no topLevel permission defined: .github/workflows/commitlint.yml:1
- Warn: no topLevel permission defined: .github/workflows/release-please.yml:1
- Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:14
- Warn: no topLevel permission defined: .github/workflows/size-limit.yml:1
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Score
6.9
/10
Last Scanned on 2025-07-03T04:41:30Z
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More