react-html-parser
v2.0.2
Published
Parse HTML into React components
Downloads
1,116,492
Maintainers
Readme
React HTML Parser
A utility for converting HTML strings into React components. Avoids the use of dangerouslySetInnerHTML and converts standard HTML elements, attributes and inline styles into their React equivalents.
Install
npm install react-html-parser
# or
yarn add react-html-parser
Usage
import React from 'react';
import ReactHtmlParser, { processNodes, convertNodeToElement, htmlparser2 } from 'react-html-parser';
class HtmlComponent extends React.Component {
render() {
const html = '<div>Example HTML string</div>';
return <div>{ ReactHtmlParser(html) }</div>;
}
}
API
function ReactHtmlParser(html, [options])
Takes an HTML string and returns equivalent React elements
Usage
import ReactHtmlParser from 'react-html-parser';
Arguments
html
: The HTML string to parseoptions
: Options object- decodeEntities=true (boolean): Whether to decode html entities (defaults to true)
- transform (function): Transform function that is applied to every node
- preprocessNodes (function): Pre-process the nodes generated by
htmlparser2
Transform Function
The transform function will be called for every node that is parsed by the library.
function transform(node, index)
Arguments
node
: The node being parsed. This is the htmlparser2 node object. Full details can be found on their project page but important properties are:type
(string): The type of node (tag, text, style etc)name
(string): The name of the nodechildren
(array): Array of children nodesnext
(node): The node's next siblingprev
(node): The node's previous siblingparent
(node): The node's parentdata
(string): The text content, if thetype
is text
index
(number): The index of the node in relation to it's parent
Return Types
return null
Returning null will prevent the node and all of it's children from being rendered.
function transform(node) {
// do not render any <span> tags
if (node.type === 'tag' && node.name === 'span') {
return null;
}
}
return undefined
If the function does not return anything, or returns undefined, then the default behaviour will occur and the parser will continue was usual.
return React element
React elements can be returned directly
import React from 'react';
function transform(node) {
if (node.type === 'tag' && node.name === 'b') {
return <div>This was a bold tag</div>;
}
}
preprocessNodes Function
Allows pre-processing the nodes generated from the html by htmlparser2
before being passed to the library and converted to React elements.
function preprocessNodes(nodes)
Arguments
nodes
: The entire node tree generated byhtmlparser2
.
Return type
The preprocessNodes
function should return a valid htmlparser2
node tree.
function convertNodeToElement(node, index, transform)
Processes a node and returns the React element to be rendered. This function can be used in conjunction with the previously described transform
function to continue to process a node after modifying it.
Usage
import { convertNodeToElement } from 'react-html-parser';
Arguments
node
: The node to processindex
(number): The index of the node in relation to it's parenttransform
: The transform function as described above
import { convertNodeToElement } from 'react-html-parser';
function transform(node, index) {
// convert <ul> to <ol>
if (node.type === 'tag' && node.name === 'ul') {
node.name = 'ol';
return convertNodeToElement(node, index, transform);
}
}
htmlparser2
The library exposes the htmlparser2
library it uses. This allows consumers
to use it without having to add it as a separate dependency.
See https://github.com/fb55/htmlparser2 for full details.