gem-hunter

html-react-parser

HTMLReactParser(string[, options])

Example

import parse from 'html-react-parser';

parse('<p>Hello, World!</p>'); // React.createElement('p', {}, 'Hello, World!')

Install

npm install html-react-parser --save

yarn add html-react-parser

<!-- HTMLReactParser depends on React -->
<script src="https://unpkg.com/react@18/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 parse from 'html-react-parser';

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

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

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

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

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

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

replace

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: {}
}

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

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

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

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

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

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

replace element and children

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>
      );
    }
  },
};

parse(html, options);

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

replace element attributes

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

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

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

parse(html, options);

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

replace and remove element

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

<p></p>

transform

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

library

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

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

htmlparser2

Warning

htmlparser2 options do not work on the client-side (browser); they only work on the server-side (Node.js). By overriding the options, it can break universal rendering.

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

trim

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

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

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

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

trustedTypePolicy

parse('<div>Hello</div>', {
  trustedTypePolicy: window.trustedTypes?.createPolicy('my-policy', {
    createHTML(input) {
      // apply sanitization logic here
      return DOMPurify.sanitize(input);
    },
  }),
});

Migration

v6

v5

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

Argument of type 'ChildNode[]' is not assignable to parameter of type 'DOMNode[]'.

domToReact(domNode.children as DOMNode[], options);

v4

v3

v2

v1

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

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

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

parse('<div /><div />'); // returns single element instead of array of elements

Don't change case of tags

const options = {
  htmlparser2: {
    lowerCaseTags: false,
  },
};
parse('<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'

Can I enable trim for certain elements?

Webpack build warnings

export 'default' (imported as 'parse') was not found in 'html-react-parser'

// webpack.config.js
module.exports = {
  // ...
  resolve: {
    mainFields: ['browser', 'main', 'module'],
  },
};

TypeScript error

node_modules/htmlparser2/lib/index.d.ts:2:23 - error TS1005: ',' expected.

2 export { Parser, type ParserOptions };
                        ~~~~~~~~~~~~~

Performance

npm run benchmark

html-to-react - Single x 1,270,990 ops/sec ±0.21% (100 runs sampled)
html-to-react - Multiple x 522,472 ops/sec ±0.64% (94 runs sampled)
html-to-react - Complex x 54,028 ops/sec ±0.82% (98 runs sampled)

npx size-limit

Contributors

Code Contributors

Financial Contributors

Individuals

Organizations

Support

License