A lightweight react library that converts raw HTML to a React DOM structure.

Overview

html-to-react

Greenkeeper badge Build Status npm version Dependency Status Coverage Status npm

A lightweight library that converts raw HTML to a React DOM structure.

Why?

I had a scenario where an HTML template was generated by a different team, yet I wanted to leverage React for the parts I did have control over. The template basically contains something like:

">
<div class="row">
  <div class="col-sm-6">
    <div data-report-id="report-1">
      
    div>
  div>
  <div class="col-sm-6">
    <div data-report-id="report-2">
      
    div>
  div>
div>

I had to replace each

that contains a data-report-id attribute with an actual report, which was nothing more than a React component.

Simply replacing the

elements with a React component would end up with multiple top-level React components that have no common parent.

The html-to-react module solves this problem by parsing each DOM element and converting it to a React tree with one single parent.

Installation

$ npm install --save html-to-react

Examples

Simple

The following example parses each node and its attributes and returns a tree of React elements.

const ReactDOMServer = require('react-dom/server');
const HtmlToReactParser = require('html-to-react').Parser;

const htmlInput = '
     

Title

A paragraph

'
; const htmlToReactParser = new HtmlToReactParser(); const reactElement = htmlToReactParser.parse(htmlInput); const reactHtml = ReactDOMServer.renderToStaticMarkup(reactElement); assert.equal(reactHtml, htmlInput); // true

With Custom Processing Instructions

If certain DOM nodes require specific processing, for example if you want to capitalize each

tag, the following example demonstrates this:

const ReactDOMServer = require('react-dom/server');
const HtmlToReact = require('html-to-react');
const HtmlToReactParser = require('html-to-react').Parser;

const htmlInput = '
      

Title

Paragraph

Another title

'
; const htmlExpected = '

TITLE

Paragraph

ANOTHER TITLE

'
; const isValidNode = function () { return true; }; // Order matters. Instructions are processed in the order they're defined const processNodeDefinitions = new HtmlToReact.ProcessNodeDefinitions(React); const processingInstructions = [ { // Custom

processing shouldProcessNode: function (node) { return node.parent && node.parent.name && node.parent.name === 'h1'; }, processNode: function (node, children) { return node.data.toUpperCase(); } }, { // Anything else shouldProcessNode: function (node) { return true; }, processNode: processNodeDefinitions.processDefaultNode } ]; const htmlToReactParser = new HtmlToReactParser(); const reactComponent = htmlToReactParser.parseWithInstructions(htmlInput, isValidNode, processingInstructions); const reactHtml = ReactDOMServer.renderToStaticMarkup(reactComponent); assert.equal(reactHtml, htmlExpected);

Replace the Children of an Element

There may be a situation where you want to replace the children of an element with a React component. This is beneficial if you want to:

  • a) Preserve the containing element
  • b) Not rely on any child node to insert your React component

Example

Below is a simple template that could get loaded via ajax into your application

Before

Sample Heading

Sample Text

">
<div class="row">
  <div class="col-sm-6">
    <div data-container="wysiwyg">
      <h1>Sample Headingh1>
      <p>Sample Textp>
    div>
  div>
div>
After

You may want to extract the inner html from the data-container attribute, store it and then pass it as a prop to your injected RichTextEditor.

Sample heading

Sample Text

"} />
">
<div class="row">
  <div class="col-sm-6">
    <div data-container="wysiwyg">
      <RichTextEditor html={"<h1>Sample headingh1><p>Sample Textp>"} />
    div>
  div>
div>

Setup

In your instructions object, you must specify replaceChildren: true.

Text

Text

'; const htmlExpected = '

Heading

'; const isValidNode = function () { return true; }; const processNodeDefinitions = new HtmlToReact.ProcessNodeDefinitions(React); // Order matters. Instructions are processed in // the order they're defined const processingInstructions = [ { // This is REQUIRED, it tells the parser // that we want to insert our React // component as a child replaceChildren: true, shouldProcessNode: function (node) { return node.attribs && node.attribs['data-test'] === 'foo'; }, processNode: function (node, children, index) { return React.createElement('h1', {key: index,}, 'Heading'); } }, { // Anything else shouldProcessNode: function (node) { return true; }, processNode: processNodeDefinitions.processDefaultNode, }, ]; const reactComponent = htmlToReactParser.parseWithInstructions( htmlInput, isValidNode, processingInstructions); const reactHtml = ReactDOMServer.renderToStaticMarkup( reactComponent); assert.equal(reactHtml, htmlExpected); ">
const React = require('react');
const HtmlToReact = require('html-to-react');
const HtmlToReactParser = require('html-to-react').Parser;

const htmlToReactParser = new HtmlToReactParser();
const htmlInput = '
  

Text

Text

'
; const htmlExpected = '

Heading

'
; const isValidNode = function () { return true; }; const processNodeDefinitions = new HtmlToReact.ProcessNodeDefinitions(React); // Order matters. Instructions are processed in // the order they're defined const processingInstructions = [ { // This is REQUIRED, it tells the parser // that we want to insert our React // component as a child replaceChildren: true, shouldProcessNode: function (node) { return node.attribs && node.attribs['data-test'] === 'foo'; }, processNode: function (node, children, index) { return React.createElement('h1', {key: index,}, 'Heading'); } }, { // Anything else shouldProcessNode: function (node) { return true; }, processNode: processNodeDefinitions.processDefaultNode, }, ]; const reactComponent = htmlToReactParser.parseWithInstructions( htmlInput, isValidNode, processingInstructions); const reactHtml = ReactDOMServer.renderToStaticMarkup( reactComponent); assert.equal(reactHtml, htmlExpected);

With Preprocessing Instructions

There may be situations where you want to preprocess nodes before rendering them, analogously to the custom processing instructions functionality. The rationale for supporting preprocessing hooks is generally that you might want to apply more general processing to nodes, before applying custom processing hooks to filtered sets of nodes. You could accomplish the same by calling common functions from your custom processing hooks, but the preprocessing hooks API makes it more convenient.

Example

Below is a simple template in which you may want to replace div IDs, via a preprocessing hook:

Sample For First

Sample For Second

">
<div class="row">
  <div id="first" data-process="shared">
    <p>Sample For Firstp>
  div>
  <div id="second" data-process="shared">
    <p>Sample For Secondp>
  div>
div>

We want to process the above HTML into the following:

First

Second

">
<div class="row">
  <h1 id="preprocessed-first">Firsth1>
  <h2 id="preprocessed-second">Secondh2>
div>

We can accomplish that with the following script, using a combination of preprocessing and custom processing instructions:

' + '
' + '

Sample For First

' + '
' + '
' + '

Sample For Second

' + '
' + '
'; const htmlExpected = '
' + '

First

' + '

Second

' + '
'; const isValidNode = function () { return true; }; const preprocessingInstructions = [ { shouldPreprocessNode: function (node) { return node.attribs && node.attribs['data-process'] === 'shared'; }, preprocessNode: function (node) { node.attribs = {id: `preprocessed-${node.attribs.id}`,}; }, } ]; const processNodeDefinitions = new HtmlToReact.ProcessNodeDefinitions(React); const processingInstructions = [ { shouldProcessNode: function (node) { return node.attribs && node.attribs.id === 'preprocessed-first'; }, processNode: function(node, children, index) { return React.createElement('h1', {key: index, id: node.attribs.id,}, 'First'); }, }, { shouldProcessNode: function (node) { return node.attribs && node.attribs.id === 'preprocessed-second'; }, processNode: function (node, children, index) { return React.createElement('h2', {key: index, id: node.attribs.id,}, 'Second'); }, }, { shouldProcessNode: function (node) { return true; }, processNode: processNodeDefinitions.processDefaultNode, }, ]; const reactComponent = parser.parseWithInstructions(htmlInput, isValidNode, processingInstructions, preprocessingInstructions); const reactHtml = ReactDOMServer.renderToStaticMarkup(reactComponent); assert.equal(reactHtml, htmlExpected); ">
const React = require('react');
const HtmlToReact = require('html-to-react');
const HtmlToReactParser = require('html-to-react').Parser;

const htmlToReactParser = new HtmlToReactParser();
const htmlInput = '
  
' + '
' + '

Sample For First

'
+ '
'
+ '
' + '

Sample For Second

'
+ '
'
+ '
'
; const htmlExpected = '
' + '

First

'
+ '

Second

'
+ '
'
; const isValidNode = function () { return true; }; const preprocessingInstructions = [ { shouldPreprocessNode: function (node) { return node.attribs && node.attribs['data-process'] === 'shared'; }, preprocessNode: function (node) { node.attribs = {id: `preprocessed-${node.attribs.id}`,}; }, } ]; const processNodeDefinitions = new HtmlToReact.ProcessNodeDefinitions(React); const processingInstructions = [ { shouldProcessNode: function (node) { return node.attribs && node.attribs.id === 'preprocessed-first'; }, processNode: function(node, children, index) { return React.createElement('h1', {key: index, id: node.attribs.id,}, 'First'); }, }, { shouldProcessNode: function (node) { return node.attribs && node.attribs.id === 'preprocessed-second'; }, processNode: function (node, children, index) { return React.createElement('h2', {key: index, id: node.attribs.id,}, 'Second'); }, }, { shouldProcessNode: function (node) { return true; }, processNode: processNodeDefinitions.processDefaultNode, }, ]; const reactComponent = parser.parseWithInstructions(htmlInput, isValidNode, processingInstructions, preprocessingInstructions); const reactHtml = ReactDOMServer.renderToStaticMarkup(reactComponent); assert.equal(reactHtml, htmlExpected);

Tests & Coverage

Test locally: $ npm test

Test with coverage and report coverage to Coveralls: $ npm run test-coverage

Test with coverage and open HTML report: $ npm run test-html-coverage

Issues