What is html-react-parser?
The html-react-parser package is designed to convert HTML strings into React components. This is particularly useful when you need to dynamically render HTML content in a React application, such as content fetched from a CMS or API that returns HTML. It allows for custom handling of elements, attributes, and can work with server-side rendering.
What are html-react-parser's main functionalities?
Parsing HTML strings to React Elements
This feature allows you to convert a string of HTML into React elements that can be rendered inside a React component.
import parse from 'html-react-parser';
const html = '<div>Hello World</div>';
const reactElement = parse(html);
Replacing or modifying elements during parsing
This feature allows you to define a 'replace' function in the options object that can modify or replace elements during the parsing process.
import parse, { domToReact } from 'html-react-parser';
const html = '<p id="replace">Replace me</p>';
const options = {
replace: ({ attribs, children }) => {
if (attribs && attribs.id === 'replace') {
return <span>{domToReact(children)}</span>;
}
}
};
const reactElement = parse(html, options);
Preserving custom attributes and event handlers
This feature allows you to preserve custom attributes and potentially event handlers when parsing HTML to React elements.
import parse from 'html-react-parser';
const html = '<div onclick="handleClick()">Click me</div>';
const reactElement = parse(html, {
preserveAttributes: ['onclick']
});
Other packages similar to html-react-parser
react-html-parser
react-html-parser is similar to html-react-parser in that it converts HTML strings into React components. However, it may differ in the specifics of its API and the options it provides for customization during the parsing process.
dangerously-set-html-content
dangerously-set-html-content provides a component that can be used to set raw HTML content. It is similar to using the dangerouslySetInnerHTML prop in React but encapsulated in a component for easier use. It does not offer the same level of customization or parsing capabilities as html-react-parser.
sanitize-html-react
sanitize-html-react is designed to sanitize HTML strings before they are rendered to prevent XSS attacks. It can be used in conjunction with html-react-parser to first sanitize the HTML string and then parse it into React components. It focuses more on security rather than parsing.
html-react-parser
![NPM](https://nodei.co/npm/html-react-parser.png)
![NPM downloads](https://img.shields.io/npm/dm/html-react-parser.svg?style=flat-square)
HTML to React parser that works on both the server (Node.js) and the client (browser):
HTMLReactParser(string[, options])
It converts an HTML string to one or more React elements. There's also an option to replace an element with your own.
Example:
var parse = require('html-react-parser');
parse('<div>text</div>');
CodeSandbox | JSFiddle | Repl.it | Examples
Installation
NPM:
$ npm install html-react-parser --save
Yarn:
$ yarn add html-react-parser
CDN:
<script src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script src="https://unpkg.com/html-react-parser@latest/dist/html-react-parser.min.js"></script>
<script>
window.HTMLReactParser();
</script>
Usage
Import the module:
const parse = require('html-react-parser');
import parse from 'html-react-parser';
Parse single element:
parse('<h1>single</h1>');
Parse multiple elements:
parse('<li>Item 1</li><li>Item 2</li>');
Since adjacent elements are parsed as an array, make sure to render them under a parent node:
<ul>
{parse(`
<li>Item 1</li>
<li>Item 2</li>
`)}
</ul>
Parse nested elements:
parse('<body><p>Lorem ipsum</p></body>');
Parse element with attributes:
parse(
'<hr id="foo" class="bar" data-attr="baz" custom="qux" style="top:42px;">'
);
Options
replace(domNode)
The replace
callback allows you to swap an element with another React element.
The first argument is an object with the same output as htmlparser2's domhandler:
parse('<br>', {
replace: function(domNode) {
console.dir(domNode, { depth: null });
}
});
Console output:
{ type: 'tag',
name: 'br',
attribs: {},
children: [],
next: null,
prev: null,
parent: null }
The element is replaced only if a valid React element is returned:
parse('<p id="replace">text</p>', {
replace: domNode => {
if (domNode.attribs && domNode.attribs.id === 'replace') {
return React.createElement('span', {}, 'replaced');
}
}
});
Here's an example that modifies an element but keeps the children:
import React from 'react';
import { renderToStaticMarkup } from 'react-dom/server';
import parse, { domToReact } from 'html-react-parser';
const html = `
<p id="main">
<span class="prettify">
keep me and make me pretty!
</span>
</p>
`;
const options = {
replace: ({ attribs, children }) => {
if (!attribs) return;
if (attribs.id === 'main') {
return (
<h1 style={{ fontSize: 42 }}>{domToReact(children, parserOptions)}</h1>
);
}
if (attribs.class === 'prettify') {
return (
<span style={{ color: 'hotpink' }}>
{domToReact(children, parserOptions)}
</span>
);
}
}
};
console.log(renderToStaticMarkup(parse(html, options)));
Output:
<h1 style="font-size:42px">
<span style="color:hotpink">
keep me and make me pretty!
</span>
</h1>
Here's an example that excludes an element:
parse('<p><br id="remove"></p>', {
replace: ({ attribs }) => attribs && attribs.id === 'remove' && <Fragment />
});
FAQ
Is this library XSS safe?
No, this library does not sanitize against XSS (Cross-Site Scripting). See #94.
Are <script>
tags parsed?
No, <script>
tags are skipped because react-dom does not render the contents. See #98.
My HTML attributes aren't getting called.
That's because inline event handlers like onclick
are parsed as a string rather than a function. See #73.
Testing
Run tests:
$ npm test
Run tests with coverage:
$ npm run test:coverage
Lint files:
$ npm run lint
Fix lint errors:
$ npm run lint:fix
Benchmarks
$ npm run test:benchmark
Here's an example output of the benchmarks run on a MacBook Pro 2017:
html-to-react - Single x 415,186 ops/sec ±0.92% (85 runs sampled)
html-to-react - Multiple x 139,780 ops/sec ±2.32% (87 runs sampled)
html-to-react - Complex x 8,118 ops/sec ±2.99% (82 runs sampled)
Release
Only collaborators with credentials can release and publish:
$ npm run release
$ git push --follow-tags && npm publish
Special Thanks
License
MIT