react-html-email

Modern HTML emails are a tangle of archaic HTML and inline styles. This library encapsulates the cruft into simple React components and helps avoid common pitfalls.

react-html-email provides a set of components for a standard 600px table layout (inspired by HTML Email Boilerplate). React's Supported Tags and Attributes are extended to include a few deprecated attributes useful for legacy clients. In addition, a style prop validator is included which uses Campaign Monitor's CSS Support Guide to check for potential compatibility issues across email clients.

Installation

$ npm install react-html-email

Usage

Import the library and set up React:

import ReactHTMLEmail from 'react-html-email'
 
// set up React to support a few HTML attributes useful for legacy clients 
ReactHTMLEmail.injectReactEmailAttributes()

To render a simple email:

import { Email, Item, Span, A, renderEmail } from 'react-html-email'
 
const emailHTML = renderEmail(
  <Email title="Hello World!">
    <Item align="center">
      <Span fontSize={20}>
        This is an example email made with:
        <A href="https://github.com/chromakode/react-html-email">react-html-email</A>.
      </Span>
    </Item>
  </Email>
)

You can find more examples in the examples directory of the repo.

API

`renderEmail(emailComponent)`

Render an email component to an HTML string. Adds an XHTML 1.0 Strict doctype, as per HTML Email Boilerplate.

`injectReactEmailAttributes()`

React ignores some attributes we need, such as the table align and valign properties. Call this function to expand React's attribute repertoire before using email components from the library.

`configStyleValidator(config)`

By default, inline styles passed to the style prop will be validated against Campaign Monitor's CSS Support Guide. Here are the default settings, which can be overridden using configStyleValidator:

ReactHTMLEmail.configStyleValidator({
  // When strict, incompatible style properties will result in an error. 
  strict: true,
 
  // Whether to warn when compatibility notes for a style property exist. 
  warn: true,
 
  // Platforms to consider for compatibility checks. 
  platforms: [
    'gmail',
    'gmail-android',
    'apple-mail',
    'apple-ios',
    'yahoo-mail',
    'outlook',
    'outlook-legacy',
    'outlook-web',
  ],
})

`PropTypes.style`

A PropTypes validator for checking email inline style compatibility. Used by default in the components below. Exported for use in your own components.

Components

Components in react-html-email include defaults for basic style properties, so that client styles are reset and normalized. Every component accepts a style prop which overrides the reset styles.

`<Email>`

An HTML document with a centered 600px <table> inside <table> container based on HTML Email Boilerplate.

It's necessary to always include a title prop for some clients' "open in browser" feature.

See MailChimp's HTML guide for how this works.

`<Box>`

A simplification of the <table> element, the workhorse of an HTML email design. <Box>es contain a vertical stack of <Item>s. Use them to create visual structure, filled buttons, and spacing.

`<Item>`

A subsection of a <Box>, essentially a <tr><td> unit.

`<Span>`

Use to assign styles to text.

It can be handy to create an object containing your default text styles for reuse. For example:

const textStyles = {
  fontFamily: 'Verdana',
  fontSize: 42,
  fontWeight: 'bold',
  color: 'orange',
}
 
[...]
 
<Span {...textDefaults}>Congratulations!</Span>
<Span {...textDefaults}>You won a free cruise!</Span>

`<A>`

Use to format links. Requires an href prop. Always sets target="_blank" and defaults to underline. To remove the underline, set textDecoration="none".

`<Image>`

An image, without any pesky borders, outlines, or underlines by default. Requires a src prop, and width and height to be set. You can override the default styles (such as adding a border) using the style prop.