Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/chromakode/react-html-email

Create elegant HTML email templates using React.
https://github.com/chromakode/react-html-email

Last synced: about 1 month ago
JSON representation

Create elegant HTML email templates using React.

Awesome Lists containing this project

README 

        
# react-html-email



## :warning: 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](https://chakra-ui.com/) for email. If you'd be interested in taking ownership of this project and tackling that, drop me a line at [email protected].



---



[![Build Status](https://img.shields.io/travis/chromakode/react-html-email/master.svg?style=flat-square)](https://travis-ci.org/chromakode/react-html-email)

[![Coverage Status](https://img.shields.io/codecov/c/github/chromakode/react-html-email/master.svg?style=flat-square)](https://codecov.io/github/chromakode/react-html-email?branch=master)

[![npm](https://img.shields.io/npm/v/react-html-email.svg?style=flat-square)](https://www.npmjs.com/package/react-html-email)

[![npm](https://img.shields.io/npm/l/react-html-email.svg?style=flat-square)](https://github.com/chromakode/react-html-email/blob/master/LICENSE)



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](https://github.com/chromakode/react-html-email) provides a set of components for a standard 600px table layout (inspired by [HTML Email Boilerplate](https://github.com/seanpowell/Email-Boilerplate)). React's [Supported Tags and Attributes](http://facebook.github.io/react/docs/tags-and-attributes.html) 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](https://www.campaignmonitor.com/css/) to check for potential compatibility issues across email clients.



## Installation



    $ npm install react-html-email



## Usage



To render a simple email:



```js

import { Email, Item, Span, A, renderEmail } from 'react-html-email'



const emailHTML = renderEmail(

  

    

      

        This is an example email made with:

        react-html-email.

      

    

  

)

```



You can find more examples in the [examples directory](https://github.com/chromakode/react-html-email/tree/master/examples) 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](https://github.com/seanpowell/Email-Boilerplate).



### `configStyleValidator(config)`



By default, inline styles passed to the `style` prop will be validated against [Campaign Monitor's CSS Support Guide](https://www.campaignmonitor.com/css/). Here are the default settings, which can be overridden using `configStyleValidator`:



```js

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.



### ``



An HTML document with a centered 600px `` inside `` container based on [HTML Email Boilerplate](https://github.com/seanpowell/Email-Boilerplate).



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



See [MailChimp's HTML guide](http://templates.mailchimp.com/development/html/) for how this works.



### ``



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



### ``



A subsection of a ``, essentially a `` unit.



### ``



Use to assign styles to text.



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



```js

const textDefaults = {

  fontFamily: 'Verdana',

  fontSize: 42,

  fontWeight: 'bold',

  color: 'orange',

}



[...]



Congratulations!

You won a free cruise!

```



### ``



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



### ``



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 `` component. You can see it in our [kitchenSink.jsx](https://github.com/chromakode/react-html-email/blob/master/examples/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](http://github.com/Roilan/mailchimpify) module.



## License



[MIT](https://github.com/chromakode/react-html-email/blob/master/LICENSE)