CSS Inlining

Maizzle uses the Juice library to automatically inline your CSS.

Let's first take a look at all the options available:

// config.js
module.exports = {
  inlineCSS: {
    styleToAttribute: {
      'background-color': 'bgcolor',
      'background-image': 'background',
      'text-align': 'align',
      'vertical-align': 'valign'
    },
    mergeLonghand: false,
    applySizeAttribute: {
      width: [],
      height: []
    },
    keepOnlyAttributeSizes: {
      width: [],
      height: []
    },
    preferBgColorAttribute: false,
    excludedProperties: null
  }
}

Enable CSS inlining

To enable CSS inlining, simply set inlineCSS to true:

module.exports = {
  inlineCSS: true
}

Note that if you set inlineCSS to an empty object, inlining won't take place:

module.exports = {
  // won't inline CSS, needs at least one option set
  inlineCSS: {}
}

Options

If you need control over CSS inlining, simply pass an options object to inlineCSS.

Changing these options in your environment config will apply to all Templates when building emails for that environment.

styleToAttribute

Defines which CSS properties should Juice duplicate as what HTML attributes.

For example, this property-attribute assignment:

module.exports = {
  inlineCSS: {
    styleToAttribute: {
      'background-color': 'bgcolor',
    }
  }
}

... will transform this:

<table class="bg-cool-gray-300">
  <tr>
    <td>...</td>
  </tr>
</table>

... into this:

<table bgcolor="#e2e8f0" style="background-color: #e2e8f0">
  <tr>
    <td>...</td>
  </tr>
</table>

attributeToStyle

Duplicates specified HTML attributes as inline CSS.

Enable for all supported attributes:

module.exports = {
  inlineCSS: {
    attributeToStyle: true
  }
}

Enable only for some attributes:

module.exports = {
  inlineCSS: {
    attributeToStyle: ['width', 'bgcolor', 'background']
  }
}

Supported attributes

width

Inlined as: width: ${value}${unit}

Notes: supports only px and % values (defaults to px)

height

Inlined as: height: ${value}${unit}

Notes: supports only px and % values (defaults to px)

bgcolor

Inlined as: background-color: ${value}

background

Inlined as: background-image: url('${value}')

align

On <table> elements:

• inlines float: ${value} for left or right values
• inlines margin-left: auto; margin-right: auto for center

On any other elements, gets inlined as text-align: ${value}

valign

Inlined as vertical-align: ${value}

mergeLonghand

Uses posthtml-postcss-merge-longhand to rewrite longhand CSS with shorthand syntax. Only works with margin, padding and border, and only when all sides are specified.

Something like this:

<p class="mx-2 my-4">Example</p>

... instead of becoming this:

<p style="margin-left: 2px; margin-right: 2px; margin-top: 4px; margin-bottom: 4px;">Example</p>

... becomes this:

<p style="margin: 4px 2px;">Example</p>

By default, mergeLonghand is disabled.

Enable it for all tags:

module.exports = {
  inlineCSS: {
    mergeLonghand: true
  }
}

Enable it only for a selection of tags:

module.exports = {
  inlineCSS: {
    mergeLonghand: ['td', 'div']
  }
}

To disable mergeLonghand, set it to false or simply omit it:

module.exports = {
  inlineCSS: {
    mergeLonghand: false
  }
}

applyWidthAttributes

Array of HTML elements that will receive width attributes based on inline CSS width.

Example:

module.exports = {
  inlineCSS: {
    applyWidthAttributes: ['TABLE', 'TD', 'TH']
  }
}

applyHeightAttributes

Array of HTML elements that will receive height attributes based on inline CSS height.

Example:

module.exports = {
  inlineCSS: {
    applyHeightAttributes: ['TABLE', 'TD', 'TH']
  }
}

keepOnlyAttributeSizes

Define for which elements should Maizzle keep only attribute sizes, like width="" and height="". Elements in these arrays will have their inline CSS widths and heights removed.

It's set to empty arrays by default, so that no elements are affected:

module.exports = {
  inlineCSS: {
    keepOnlyAttributeSizes: {
      width: [],
      height: []
    }
  }
}

You can add HTML elements like this:

module.exports = {
  inlineCSS: {
    keepOnlyAttributeSizes: {
      width: ['TABLE', 'TD', 'TH', 'IMG', 'VIDEO'],
      height: ['TABLE', 'TD', 'TH', 'IMG', 'VIDEO']
    }
  }
}

preferBgColorAttribute

If you're inlining your CSS and have 'background-color': 'bgcolor' in the styleToAttribute option of the inliner, you can shave off some bytes by having Maizzle keep just the bgcolor="" attribute.

Enable this option to remove any inlined background-color CSS properties:

module.exports = {
  inlineCSS: {
    preferBgColorAttribute: true
  }
}

You can optionally provide an array of tag names that it should remove the background-color inline CSS from:

module.exports = {
  inlineCSS: {
    preferBgColorAttribute: ['td'] // default: ['body', 'marquee', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'tr']
  }
}

In this case, background-color will be removed only from <td> elements.

excludedProperties

Array of CSS property names that should be excluded from the CSS inlining process. Names are considered unique, so you need to specify each one you'd like to exclude.

For example:

module.exports = {
  inlineCSS: {
    excludedProperties: ['padding', 'padding-left']
  }
}

Prevent inlining

Use the data-embed attribute on a <style> tag to prevent Juice from inlining the CSS inside it. Useful for writing email client CSS hacks, or for preserving CSS comments in tandem with the removeCSSComments: false Cleanup option.