react-html-email

⚠️ Currently Unmaintained

react-html-email is presently unmaintained. As React has matured, it is no longer as necessary to use a separate library to generate email-specific markup. I'd encourage you to look at more recent CSS-in-JS and style inlining component libraries as the basis for building your own email design system, though these components can serve as a useful starting point.

I think the future of this project would be a generic set of design components for email templates -- something akin to Chakra UI for email. If you'd be interested in taking ownership of this project and tackling that, drop me a line at [email protected].

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

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.

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 textDefaults = {
  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.jsx 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