Juice

[![CI][github-ci-shield]][github-ci] [![License][license-shield]][license]

Given HTML, Juice will inline your CSS properties into the style attribute.

Some projects using Juice →

How to use

Juice has a number of functions based on whether you want to process a file, HTML string, or a cheerio document, and whether you want Juice to automatically get remote stylesheets, scripts and image dataURIs to inline.

To inline HTML without getting remote resources, using default options:

import juice from 'juice';

const result = juice("<style>div{color:red;}</style><div/>");

result will be:

<div style="color: red;"></div>

Try out the web client version

What is this useful for?

• HTML emails. For CSS support in email clients see Can I Email.
• Embedding HTML in 3rd-party websites.

Documentation

Juice is exposed as a standard module, and from CLI with a smaller set of options.

Options

All Juice methods take an options object that can contain any of these properties, though not every method uses all of these:

| Option | Default value | Description | |--------|-------|------------| | applyAttributesTableElements | true | Create attributes for styles in juice.styleToAttribute on elements set in juice.tableElements. | | applyHeightAttributes | true | Use any CSS pixel heights to create height attributes on elements set in juice.heightElements. | | applyStyleTags | true | Inline styles in <style> tags. | | applyWidthAttributes | true | Use any CSS pixel widths to create width attributes on elements set in juice.widthElements. | | decodeStyleAttributes | false | Decode the value of style attributes. | | extraCss | "" | Extra CSS to apply to the file. | | inlineDuplicateProperties | false | When true, declarations with identical CSS properties will all be inlined, instead of only the one with the highest specificity. Useful for progressive enhancement. | | insertPreservedExtraCss | true | Whether to insert into the document any preserved @media or @font-face content from extraCss when using preserveMediaQueries, preserveFontFaces or preserveKeyFrames. <br><br> When set to true, order of preference to append the <style> element is into head, then body, then at the end of the document. <br><br> When a string the value is treated as a CSS/jQuery/cheerio selector, and when found, the <style> tag will be appended to the end of the first match. | | inlinePseudoElements | false | Insert pseudo elements (::before and ::after) as <span> into the DOM. Note: Inserting pseudo elements will modify the DOM and may conflict with CSS selectors elsewhere on the page (e.g., :last-child). | | preserveFontFaces | true | Preserve all @font-face within <style> tags as a refinement when removeStyleTags is true. Other styles are removed. | | preserveImportant | false | Preserve !important in CSS values. | | preserveMediaQueries | true | Preserve all media queries (and contained styles) within <style> tags as a refinement when removeStyleTags is true. Other styles are removed. | | preserveKeyFrames | true | Preserve all key frames within <style> tags as a refinement when removeStyleTags is true. Other styles are removed. | | preservePseudos | true | Preserve all rules containing pseudo selectors defined in ignoredPseudos within <style> tags as a refinement when removeStyleTags is true. Other styles are removed. | | preservedSelectors | [] | Array of strings that represent CSS selectors to preserve inside <style> tags when removeStyleTags or removeInlinedSelectors are true. Matches substrings. | removeInlinedSelectors | false | Remove CSS rules from <style> tags after (possibly) inlining them. Other rules are preserved. Works only if removeStyleTags is false. | | removeStyleTags | true | Remove the original <style> tags after (possibly) inlining their CSS content. Overrides removeInlinedSelectors. | | resolveCSSVariables | true | Resolve CSS variables. | | webResources | {} | An options object that will be passed to web-resource-inliner for Juice functions that will get remote resources (juiceResources and juiceFile). | | xmlMode | false | Output XML/XHTML with all tags closed. Note that the input must also be valid XML/XHTML or you will get undesirable results. |

Methods

juice(html [, options])

Returns a string containing the HTML with inlined CSS.

Does not fetch remote resources.

• html - HTML string, accepts complete documents as well as fragments
• options - optional, see Options above

juice.juiceResources(html, options, callback)

Callback returns a string containing the HTML with inlined CSS.

Fetches remote resources.

• html - (string) HTML
• options - see Options above
• callback(err, html)
  • err - Error object or null
  • html - (string) HTML with inlined CSS

juice.juiceFile(filePath, options, callback)

Callback returns a string containing the HTML with inlined CSS.

Fetches remote resources.

• filePath - path to the HTML file to be Juiced
• options - see Options above
• callback(err, html)
  • err - Error object or null
  • html - (string) HTML with inlined CSS

juice.juiceDocument($ [, options])

This takes a cheerio instance and performs inlining in-place. Returns the same cheerio instance. Does not fetch remote resources.

• $ - a cheerio instance, be sure to use the same cheerio version that Juice uses
• options - (object) optional, see Options above

juice.inlineContent(html, css [, options])

This takes HTML and CSS and returns new HTML with the provided CSS inlined.

It does not look at <style> or <link rel="stylesheet"> elements at all.

• html - HTML string
• css - CSS string
• options - (object) optional, see Options above

juice.inlineDocument($, css [, options])

Given a cheerio instance and CSS, this modifies the cheerio instance so that the provided CSS is inlined. It does not look at <style> or <link rel="stylesheet"> elements at all.

• $ - a cheerio instance, be sure to use the same cheerio version that juice uses
• css - CSS string
• options - (object) optional, see Options above

Global settings

juice.codeBlocks

Type: Object
Default:

{
  EJS: { start: '<%', end: '%>' },
  HBS: { start: '{{', end: '}}' }
}

An object where each value has a start and end to specify fenced code blocks that should be ignored during parsing and inlining.

For example, Handlebars (hbs) templates are juice.codeBlocks.HBS = {start: '{{', end: '}}'}. codeBlocks can fix problems where otherwise juice might interpret code like <= as HTML, when it is meant to be template language code.

Note that codeBlocks is a dictionary which can contain many different code blocks, so don't do juice.codeBlocks = {...} do juice.codeBlocks.myBlock = {...}

juice.ignoredPseudos

Type: Array
Default: ['hover', 'active', 'focus', 'visited', 'link']

Array of ignored pseudo-selectors such as 'hover' and 'active'.

juice.widthElements

Type: Array
Default: ['TABLE', 'TD', 'TH', 'IMG']

Array of HTML elements that can receive width attributes.

juice.heightElements

Type: Array
Default: ['TABLE', 'TD', 'TH', 'IMG']

Array of HTML elements that can receive height attributes.

juice.styleToAttribute

Type: Object
Default:

{
  'background-color': 'bgcolor',
  'background-image': 'background',
  'text-align': 'align',
  'vertical-align': 'valign'
}

Object of style property names (key) to their respective attribute names (value).

juice.tableElements

Type: Array
Default: ['TABLE', 'TH', 'TR', 'TD', 'CAPTION', 'COLGROUP', 'COL', 'THEAD', 'TBODY', 'TFOOT']

Array of table HTML elements that can receive attributes defined in juice.styleToAttribute.

juice.nonVisualElements

Type: Array
Default: [ 'HEAD', 'TITLE', 'BASE', 'LINK', 'STYLE', 'META', 'SCRIPT', 'NOSCRIPT' ]

Array of elements that will not have styles inlined because they are not intended to render.

juiceClient.excludedProperties

Type: Array
Default: []

Array of CSS properties that won't be inlined.

Special markup

data-embed

Add data-embed to any <style> tag to prevent Juice from inlining its CSS and removing it. Can be used to embed email client support hacks that rely on CSS selectors into your email templates:

<style data-embed>
  u + .body .your-class-name {
    /* CSS here targets Gmail */
  }
</style>

The data-embed attribute will be removed from the output HTML, but no inlining or style tag removal will take place:

<style>
  u + .body .your-class-name {
    /* CSS here targets Gmail */
  }
</style>

Ignoring CSS with comments

You can use special CSS comments to prevent Juice from inlining entire CSS files, rules, or even just declarations.

Ignore entire file

Add a /* juice ignore */ comment on the first line in your CSS:

<style>
  /* juice ignore */
  body { color: red; }
  .test { color: blue; }
</style>

<body>
  <div class="test">Hello World</div>
</body>

The entire CSS will be ignored (as in, not inlined).

With removeStyleTags: true, the whole <style> tag will be preserved.

Ignore next rule

Add /* juice ignore next */ before any CSS rule to skip inlining that rule:

body { color: black; }

/* juice ignore next */
h1 {
  color: blue;
}

p { color: green; }

The h1 rule will not be inlined, but will be preserved when removeStyleTags: true. The body and p rules will be inlined norma