• Install
• Usage
  • replace
    • replace with TypeScript
    • replace element and children
    • replace element attributes
    • replace and remove element
  • transform
  • library
  • htmlparser2
  • trim
• Migration
  • v5
  • v4
  • v3
  • v2
  • v1
• FAQ
  • Is this XSS safe?
  • Does invalid HTML get sanitized?
  • [Are `

## Usage

Import ES module:

```ts
import parse from 'html-react-parser';

Or require CommonJS module:

const parse = require('html-react-parser').default;

Parse single element:

parse('<h1>single</h1>');

Parse multiple elements:

parse('<li>Item 1</li><li>Item 2</li>');

Make sure to render parsed adjacent elements under a parent element:

<ul>
  {parse(`
    <li>Item 1</li>
    <li>Item 2</li>
  `)}
</ul>

Parse nested elements:

parse('<p>Lorem ipsum</p>');

Parse element with attributes:

parse(
  '<hr style="top:42px;" data-attr="baz" class="bar" id="foo">',
);

replace

The replace option allows you to replace an element with another element.

The replace callback's first argument is domhandler's node:

parse('<br>', {
  replace(domNode) {
    console.dir(domNode, { depth: null });
  },
});

Element {
  type: 'tag',
  parent: null,
  prev: null,
  next: null,
  startIndex: null,
  endIndex: null,
  children: [],
  name: 'br',
  attribs: {}
}

The element is replaced if a valid React element is returned:

parse('<p id="replace">text</p>', {
  replace(domNode) {
    if (domNode.attribs &amp;&amp; domNode.attribs.id === 'replace') {
      return <span>replaced</span>;
    }
  },
});

The second argument is the index:

parse('<br>', {
  replace(domNode, index) {
    console.assert(typeof index === 'number');
  },
});

> [!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

For TypeScript, you'll need to check that domNode is an instance of domhandler's Element:

import { HTMLReactParserOptions, Element } from 'html-react-parser';

const options: HTMLReactParserOptions = {
  replace(domNode) {
    if (domNode instanceof Element && domNode.attribs) {
      // ...
    }
  },
};

Or use a type assertion:

import { HTMLReactParserOptions, Element } from 'html-react-parser';

const options: HTMLReactParserOptions = {
  replace(domNode) {
    if ((domNode as Element).attribs) {
      // ...
    }
  },
};

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):

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="{{">{domToReact(children, options)}</h1>;
    }

    if (attribs.class === 'prettify') {
      return (
        <span style="{{">
          {domToReact(children, options)}
        </span>
      );
    }
  },
};

parse(html, options);

</p><h1 style="font-size:42px">
  <span style="color:hotpink">
    keep me and make me pretty!
  </span>
</h1>

replace element attributes

Convert DOM attributes to React props with attributesToProps:

import parse, { attributesToProps } from 'html-react-parser';

const html = `
  <main style="background: #fff; text-align: center;" class="prettify">
`;

const options = {
  replace(domNode) {
    if (domNode.attribs &amp;&amp; domNode.name === 'main') {
      const props = attributesToProps(domNode.attribs);
      return <div>;
    }
  },
};

parse(html, options);

</p><div style="background:#fff;text-align:center" class="prettify"></div>

replace and remove element

Exclude an element from rendering by replacing it with ``:

parse('<p><br></p>', {
  replace: ({ attribs }) =&gt; attribs?.id === 'remove' &amp;&amp; &lt;&gt;,
});

</p><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:

parse('<br>', {
  transform(reactNode, domNode, index) {
    // this will wrap every element in a div
    return <div>{reactNode}</div>;
  },
});

library

The library option specifies the UI library. The default library is React.

To use Preact:

parse('<br>', {
  library: require('preact'),
});

Or a custom library:

parse('<br>', {
  library: {
    cloneElement: () =&gt; {
      /* ... */
    },
    createElement: () =&gt; {
      /* ... */
    },
    isValidElement: () =&gt; {
      /* ... */
    },
  },
});

htmlparser2

> [!WARNING] > htmlparser2 options don't work on the client-side (browser) and 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:

parse('<p></p><p>', {
  htmlparser2: {
    xmlMode: true,
  },
});

trim

By default, whitespace is preserved:

parse('<br>\n'); // [React.createElement('br'), '\n']

But certain elements like `` will strip out invalid whitespace:

parse('<table></table><table></table>\n'); // React.createElement('table')

To remove whitespace, enable the trim option:

parse('<br>\n', { trim: true }); // React.createElement('br')

However, intentional whitespace may be stripped out:

parse('</p><p> </p>', { trim: true }); // React.createElement('p')

Migration

v5

Migrated to TypeScript. CommonJS imports require the .default key:

const 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:

domToReact(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:

import { Element } from 'domhandler/lib/node';

parse('<br class="remove">', {
  replace(domNode) {
    if (domNode instanceof Element &amp;&amp; domNode.attribs.class === 'remove') {
      return &lt;&gt;;
    }
  },
});

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 `