react-html-email

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 {injectReactEmailAttributes} from 'react-html-email'

// set up React to support a few HTML attributes useful for legacy clients
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.

Head CSS and Media Queries

You can pass a string prop headCSS to your <Email> component. You can see it in our kitchenSink.js example.

Mailchimp attributes

If you're using Mailchimp and need to add their custom mc:edit attributes to your markup, we recommend using the mailchimpify module.

License

MIT

Changelog

2.0.0 - 2017-09-24

Added

• Add "download" prop to the A component. (@joewescott)

Changed

• React > 15.4.0 is required. This allows removal of the fallback import to react/lib/DOMProperty which caused problems with Webpack compilation. (@chromakode)
• Email component now defaults to including a lang="en" attribute. (@chromakode)
• Use standalone prop-types package. (@taylorwinfield)

Fixed

• Bug where compatibility notes for CSS properties might not be warned if an unknown property was used. (@chromakode)