html-to-react

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

Project Moved

As part of #43, this project moved to https://github.com/aknuds1/html-to-react. Please file any issues or PRs at the new location.

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">
          <!-- A React component for report-1 -->
        </div>
    </div>
    <div class="col-sm-6">
        <div data-report-id="report-2">
          <!-- A React component for report-2 -->
        </div>
    </div>
</div>

I had to replace each <div> that contains a data-report-id attribute with an actual report, which was nothing more than a React component.

Simply replacing the <div> 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 components.

var React = require('react');
var HtmlToReact = new require('html-to-react');

var htmlInput = '<div><h1>Title</h1><p>A paragraph</p></div>';
var htmlToReactParser = new HtmlToReact.Parser(React);
var reactComponent = htmlToReactParser.parse(htmlInput);
var reactHtml = React.renderToStaticMarkup(reactComponent);

assert.equal(reactHtml, htmlInput); // true

With custom processing instructions

If certain DOM nodes require specific processing, for example if you want to capitalize each <h1> tag, the following example demonstrates this:

var React = require('react');
var HtmlToReact = new require('html-to-react');

var htmlInput = '<div><h1>Title</h1><p>Paragraph</p><h1>Another title</h1></div>';
var htmlExpected = '<div><h1>TITLE</h1><p>Paragraph</p><h1>ANOTHER TITLE</h1></div>';

var isValidNode = function() {
    return true;
};

// Order matters. Instructions are processed in the order they're defined
var processNodeDefinitions = new HtmlToReact.ProcessNodeDefinitions(React);
var processingInstructions = [
    {
        // Custom <h1> 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
    }];
var htmlToReactParser = new HtmlToReact.Parser(React);
var reactComponent = htmlToReactParser.parseWithInstructions(htmlInput, isValidNode, processingInstructions);
var reactHtml = React.renderToStaticMarkup(reactComponent);
assert.equal(reactHtml, htmlExpected);

Tests & Coverage

$ npm run test-locally

$ npm run test-html-coverage