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. There's also an option to replace an element with your own.

Example:

var parse = require('html-react-parser');
parse('<div>text</div>'); // equivalent to `React.createElement('div', {}, 'text')`

CodeSandbox | JSFiddle | Repl.it | Examples

Installation

NPM:

$ npm install html-react-parser --save

Yarn:

$ yarn add html-react-parser

CDN:

<!-- HTMLReactParser depends on React -->
<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(/* string */);
</script>

Usage

Import the module:

// CommonJS
const parse = require('html-react-parser');

// ES Modules
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, options)}</h1>;
    }

    if (attribs.class === 'prettify') {
      return (
        <span style={{ color: 'hotpink' }}>
          {domToReact(children, options)}
        </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 is not XSS (Cross-Site Scripting) safe. See #94.

Does this library sanitize invalid HTML?

No, this library does not perform HTML sanitization. See #124.

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.

Why aren't my HTML attributes getting called?

This is because inline event handlers (e.g., onclick) are parsed as a string instead of a function. See #73.

Testing

Run tests:

$ npm test

Run tests with coverage:

$ npm run test:coverage

View coverage in browser:

$ npm run test:coverage:report
$ open coverage/index.html

Lint files:

$ npm run lint
$ npm run dtslint

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

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

MIT

linkelvin11/html-react-parser