@frontity/html2react

This package is in charge of converting HTML to React. It works with processors that match HTML portions and replaces them with React components.
Table of Contents
​Installation​
​Settings​
​How to use​
​Rendering the parsed content​
​Processors​
​Loading processors​
​Creating your own processors​
​Example​
​Nodes​
​Default Processors​
​Script​
​Usage​
​Iframe​
​Usage​
​API Reference​
​Libraries​
​libraries.html2react.processors​
​libraries.html2react.Component​
Installation
Add the html2react package to your project:
1
npm i @frontity/html2react
Copied!
Settings
This package needs to be included in your frontity.settings.js file as one of the packages that will be part of the Frontity project:
frontity.settings.js
1
module.exports = {
2
  packages: ["@frontity/html2react"],
3
};
Copied!
If you use an already created theme this package will already be configured so you don't need to do anything else.
If you're creating a custom theme you'll have to define the processors you want to use in the configuration of the package.
How to use
Rendering the parsed content
This is how you need to include the Component that will render the parsed content. The only prop it takes is html, and you'll usually pass post.content.rendered to it:
1
import React from "react";
2
​
3
const Post = ({ state, libraries }) => {
4
  const data = state.source.get(state.router.link);
5
  const post = state.source[data.type][data.id];
6
​
7
  // Component exposed by html2react.
8
  const Html2React = libraries.html2react.Component;
9
​
10
  return (
11
    <div>
12
      <Title />
13
      <AuthorAndDate />
14
      <FeaturedImage />
15
      {/* Use Html2React to render the post HTML content */}
16
      <Html2React html={post.content.rendered} />
17
    </div>
18
  );
19
};
Copied!
Processors
Processors are the blocks of logic used by html2react to detect specific portions of HTML and return custom HTML or React components.
The processors field is an array where you can push all the processors you want to use with html2react. You can check the default processors here.
Loading processors
You can add your processors directly in libraries.html2react.processors. Here you can see as an example how this is done in mars-theme:
1
import image from "@frontity/html2react/processors/image";
2
import customProcessor from "./processors/custom";
3
​
4
const myPackage = {
5
  roots: { ... },
6
  state: { ... },
7
  actions: { ... },
8
  libraries: {
9
    html2react: {
10
      processors: [image, customProcessor]
11
    }
12
  }
13
};
14
​
15
export default myPackage;
Copied!
Creating your own processors
A processor is an object with four properties: name , priority , test,and processor.
Name
Type
Required
Description
name
string
yes
the name of your processor
priority
number
yes
A number that lets the package know in which order processors should be evaluated. The processors are evaluated in numeric order. For example, a processor with priority of 10 will be applied before a processor with a priority of 20
test
function
yes
A function that evaluate each node, and if it returns true, this node will be passed down to the processor function
processor
function
yes
A function to apply some logic to the node that we want to modify. It could be substituting HTML tags for React component with some logic, as adding lazy-loading to images, or just modifying some attributes, like adding target="_blank" to the links.
Both the test and the processor functions receive the same arguments ({ node, root, state, libraries })
Name
Type
Description
node
object
The HTML node tag the processor is evaluating
root
object
The top node of the node tree
state
object
Access to Frontity's state . This could be useful to use some parts of the state inside your processor. For example, using your state.theme.colors
libraries
object
Access to Frontity's libraries. As it happens with the state, sometimes could be useful to access your libraries as well
The test function returns a boolean to indicate processor function should be executed (the node matches the pattern).
The processor function returns a node object.
Example
This is how the image processor is implemented in html2react:
1
import Image from "@frontity/components/image";
2
​
3
const image = {
4
  // We can add a name to identify it later.
5
  name: "image",
6
​
7
  // We can add a priority so it executes before or after other processors.
8
  priority: 10,
9
​
10
  // Only process the node it if it's an image.
11
  test: ({ node }) => node.component === "img",
12
​
13
  processor: ({ node }) => {
14
    // If the image is inside a <noscript> tag, we don't want to process it.
15
    if (node.parent.component === "noscript") return null;
16
​
17
    // Many WP lazy load plugins move the real "src" to "data-src", so we move it back.
18
    if (node.props["data-src"]) node.props.src = node.props["data-src"];
19
    if (node.props["data-srcset"])
20
      node.props.srcSet = node.props["data-srcset"];
21
​
22
    // We tell Html2React that it should use the <Image /> component
23
    // from @frontity/components, which includes lazy loading support.
24
    node.component = Image;
25
​
26
    return node;
27
  },
28
};
29
​
30
export default image;
Copied!
You don't need to return a React component, you can also modify the attributes (props) of the node. For example, this processor adds target="_blank" to the <a> tags with href starting with http:
1
const extAnchors = {
2
  name: "external anchors",
3
  priority: 10,
4
  // Only process the node it if it's an anchor and href starts with http.
5
  test: ({ node }) =>
6
    node.component === "a" && node.props.href.startsWith("http"),
7
  // Add the target attribute.
8
  processor: ({ node }) => {
9
    node.props.target = "_blank";
10
    return node;
11
  },
12
};
Copied!
Nodes
The object node received by both test and processorcan be an Element, a Text or a Comment. You can distinguish between them using node.type.
An Element is an HTML tag or a React component.
A Text is a text content. For example, the text inside a <p> tag.
A Comment is just an HTML comment. Like this <!-- comment -->.
The common properties are:
Name
Type
Description
​
​
type
string
The Node type. </br> Possible values: `"element"
"text"
"comment"`
parent
Element
The parent of this node, which is always an element (text or comment can't have children)
​
​
ignore
boolean
If you set ignore to true for a node, it won't pass any test. This is useful in some situations when you don't want additional processors applied to this node.
​
​
Besides common properties, Element nodes are also defined by the following properties:
Name
Type
Description
component
string or function (React component)
If it's a string, it's an HTML tag and if it's a function is a React component. You can change it at will and it is what you would usually do when you want to convert HTML tags to React components
props
object
An object containing all the HTML attributes of that node or props of that React component. You can also change them at will. All the attributes are converted to the React equivalents, even for HTML tags.
children
array (of nodes)
An array containing other nodes, children to this one. If you want to get rid of the children, just overwrite it with null or an empty array
Examples of props values (and their equivalent React props):
class -> className
style -> css
srcset -> srcSet
onclick -> onClick
..
Besides common properties, Text and Comment nodes will also have the following property:
Name
Type
Description
content
string
Content of the Node
Default Processors
Script
React doesn’t execute the code inside a <script> tags. For that reason, html2react doesn’t execute the script tags included in the contents.
The script processor, with a priority of 20, processes <script> tags found in the HTML for execution. <script> type must either be application/javascript, text/javascript or application/ecmascript to pass the test of the processor.
Usage
The script processor is included by default in html2react. Therefore, no extra procedure is required to use the processor.
Iframe
Iframes can impact the loading time and performance of a site. The iframe processor adds lazy-loading to the <iframe> tags found in the HTML.
Usage
Add iframe to the processors array in your package index.js file.
1
import iframe from "@frontity/html2react/processors/iframe";
2
​
3
const themeName = {
4
    name: "theme-name",
5
    ...
6
    libraries: {
7
        html2react: {
8
            processors: [iframe]
9
        }
10
    }
11
}
Copied!
API Reference
Libraries
libraries.html2react.processors
An array of the processors that will be used by html2react.
You can add, remove or mutate any processor from the array:
1
// Add a processor.
2
libraries.html2react.processors.push(image);
3
​
4
// Remove a processor.
5
const index = libraries.html2react.processors.findIndex(
6
  (pr) => pr.name === "image"
7
);
8
libraries.html2react.processors.splice(index, 1);
9
​
10
// Change a processor priority.
11
const processor = libraries.html2react.processors.find(
12
  (pr) => pr.name === "image"
13
);
14
processor.priority = 20;
Copied!
libraries.html2react.Component
The React component used to render the parsed HTML.
Props
Name
Type
Required
Description
html
string
yes
The HTML that needs to be rendered
1
import React from "react";
2
​
3
const Post = ({ libraries }) => {
4
  // Get the component exposed by html2react.
5
  const Html2React = libraries.html2react.Component;
6
​
7
  return (
8
    <>
9
      {/* Use it to render the HTML. */}
10
      <Html2React html={html} />
11
    </>
12
  );
13
};
Copied!