# html-react-parser
[](https://nodei.co/npm/html-react-parser/)
[](https://www.npmjs.com/package/html-react-parser)
[](https://travis-ci.org/remarkablemark/html-react-parser)
[](https://coveralls.io/github/remarkablemark/html-react-parser?branch=master)
[](https://david-dm.org/remarkablemark/html-react-parser)
[](https://www.npmjs.com/package/html-react-parser)
[](https://opencollective.com/html-react-parser)
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](https://reactjs.org/docs/react-api.html#creating-react-elements). There's also an option to [replace an element](#replacedomnode) with your own.
#### Example:
```js
var parse = require('html-react-parser');
parse('text
'); // equivalent to `React.createElement('div', {}, 'text')`
```
[CodeSandbox](https://codesandbox.io/s/940pov1l4w) | [JSFiddle](https://jsfiddle.net/remarkablemark/7v86d800/) | [Repl.it](https://repl.it/@remarkablemark/html-react-parser) | [Examples](https://github.com/remarkablemark/html-react-parser/tree/master/examples)
## Installation
[NPM](https://www.npmjs.com/package/html-react-parser):
```sh
$ npm install html-react-parser --save
```
[Yarn](https://yarnpkg.com/package/html-react-parser):
```sh
$ yarn add html-react-parser
```
[CDN](https://unpkg.com/html-react-parser/):
```html
```
## Usage
Import the module:
```js
// ES Modules
import parse from 'html-react-parser';
// CommonJS
const parse = require('html-react-parser');
```
Parse single element:
```js
parse('single
');
```
Parse multiple elements:
```js
parse('Item 1Item 2');
```
Since adjacent elements are parsed as an array, make sure to render them under a parent node:
```jsx
{parse(`
- Item 1
- Item 2
`)}
```
Parse nested elements:
```js
parse('Lorem ipsum
');
```
Parse element with attributes:
```js
parse(
'
'
);
```
### 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](https://github.com/fb55/htmlparser2/tree/v3.10.1)'s [domhandler](https://github.com/fb55/domhandler#example):
```js
parse('
', {
replace: function (domNode) {
console.dir(domNode, { depth: null });
}
});
```
Console output:
```js
{ type: 'tag',
name: 'br',
attribs: {},
children: [],
next: null,
prev: null,
parent: null }
```
The element is replaced only if a _valid_ React element is returned:
```js
parse('text
', {
replace: domNode => {
if (domNode.attribs && domNode.attribs.id === 'replace') {
return React.createElement('span', {}, 'replaced');
}
}
});
```
Here's an [example](https://repl.it/@remarkablemark/html-react-parser-replace-example) that modifies an element but keeps the children:
```jsx
import React from 'react';
import { renderToStaticMarkup } from 'react-dom/server';
import parse, { domToReact } from 'html-react-parser';
const html = `
keep me and make me pretty!
`;
const options = {
replace: ({ attribs, children }) => {
if (!attribs) return;
if (attribs.id === 'main') {
return {domToReact(children, options)}
;
}
if (attribs.class === 'prettify') {
return (
{domToReact(children, options)}
);
}
}
};
console.log(renderToStaticMarkup(parse(html, options)));
```
Use the exported attributesToProps method to convert DOM attributes to React Props:
```jsx
import React from 'react';
import parse, { attributesToProps } from 'html-react-parser';
const html = `
`;
const options = {
replace: node => {
if (node.attribs && node.name === 'hr') {
const props = attributesToProps(node.attribs);
return
;
}
}
};
```
Output:
```html
keep me and make me pretty!
```
Here's an [example](https://repl.it/@remarkablemark/html-react-parser-56) that excludes an element:
```jsx
parse('
', {
replace: ({ attribs }) => attribs && attribs.id === 'remove' &&
});
```
### library
The `library` option allows you to specify which component library is used to create elements. React is used by default if this option is not specified.
Here's an example showing how to use Preact:
```js
parse('
', {
library: require('preact')
});
```
Or, using a custom library:
```js
parse('
', {
library: {
cloneElement: () => {
/* ... */
},
createElement: () => {
/* ... */
},
isValidElement: () => {
/* ... */
}
}
});
```
### htmlparser2
This library passes the following options to [htmlparser2](https://github.com/fb55/htmlparser2/tree/v3.10.1) on the server-side:
```js
{
decodeEntities: true,
lowerCaseAttributeNames: false
}
```
By passing your own options, the default library options will be **replaced** (not merged).
As a result, to enable `decodeEntities` and `xmlMode`, you need to do the following:
```js
parse('', {
htmlparser2: {
decodeEntities: true,
xmlMode: true
}
});
```
See [htmlparser2 options](https://github.com/fb55/htmlparser2/wiki/Parser-options).
> **Warning**: By overriding htmlparser2 options, there's a chance of breaking universal rendering. Do this at your own risk.
### trim
Normally, whitespace is preserved:
```js
parse('
\n'); // [React.createElement('br'), '\n']
```
By enabling the `trim` option, whitespace text nodes will be skipped:
```js
parse('
\n', { trim: true }); // React.createElement('br')
```
This addresses the warning:
```
Warning: validateDOMNesting(...): Whitespace text nodes cannot appear as a child of . Make sure you don't have any extra whitespace between tags on each line of your source code.
```
However, this option may strip out intentional whitespace:
```js
parse('
', { trim: true }); // React.createElement('p')
```
## FAQ
#### Is this library XSS safe?
No, this library is _**not**_ [XSS (cross-site scripting)](https://wikipedia.org/wiki/Cross-site_scripting) safe. See [#94](https://github.com/remarkablemark/html-react-parser/issues/94).
#### Does this library sanitize invalid HTML?
No, this library does _**not**_ perform HTML sanitization. See [#124](https://github.com/remarkablemark/html-react-parser/issues/124), [#125](https://github.com/remarkablemark/html-react-parser/issues/125), and [#141](https://github.com/remarkablemark/html-react-parser/issues/141).
#### Are `