How to use CSS background gradients in HTML emails

Learn how to add CSS background image gradients with Outlook VML fallback to your HTML email templates in Maizzle

Many email clients support CSS background gradients.

In this tutorial, you will learn how to use the tailwindcss-gradients plugin to add colorful gradients to your HTML email templates. We will also cover how to add a VML fallback for Outlook on Windows.

Getting started

Let’s start by creating a new Maizzle project.

npx create-maizzle

In the interactive setup wizard, specify the directory name to create the project in, i.e. ./example-gradients, and select the Default Starter.

Choose Yes when prompted to Install dependencies.

After dependencies finish installing, change the current directory to example-gradients:

cd example-gradients

Next, install the tailwindcss-gradients plugin:

npm install tailwindcss-gradients

Once it finishes, open the example-gradients folder in your favorite code editor.

CSS Gradients

Let’s configure and use tailwindcss-gradients with Tailwind CSS.

Tailwind CSS config

We need to tell Tailwind CSS to use the plugin. Edit tailwind.config.js and require() the plugin inside the plugins: [] array:

tailwind.config.js

module.exports = {
  plugins: [
    require('tailwindcss-gradients'),
  ]
}

Next, we need to define what kind of gradients we want to generate, based on which colors. We do that in the theme: {} key from tailwind.config.js.

For example, let’s register linear gradients based on the existing color palette:

tailwind.config.js

module.exports = {
  theme: {
    linearGradientColors: theme => theme('colors'),
  }
}

tailwindcss-gradients can generate many other types of gradients (although not all are supported in email). See all configuration options.

Use in HTML

Simply add the utility class on an element that supports background-image CSS.

We also specify a background color first, so that email clients that don’t support CSS background-image gradients can display a fallback:

emails/example.html

<x-main>
  <table class="w-full">
    <tr>
      <td class="bg-gray-200 bg-gradient-b-black">
        <!-- ... -->
      </td>
    </tr>
  </table>
</x-main>

Outlook VML

Outlook for Windows doesn’t support CSS gradients, but we can use VML.

You need to add it right after the element with the CSS gradient class:

emails/example.html

<x-main>
  <table class="w-full">
    <tr>
      <td class="bg-blue-500 bg-gradient-b-black-transparent">
        <!--[if gte mso 9]>
        <v:rect xmlns:v="urn:schemas-microsoft-com:vml" fill="true" stroke="false" style="width:600px;">
        <v:fill type="gradient" color="#0072FF" color2="#00C6FF" angle="90" />
        <v:textbox style="mso-fit-shape-to-text:true" inset="0,0,0,0">
        <div><![endif]-->
        [your overlayed HTML here]
        <!--[if gte mso 9]></div></v:textbox></v:rect><![endif]-->
      </td>
    </tr>
  </table>
</x-main>

As you can see, you need to set a fixed width on the <v:rect> element - it is recommended instead of using mso-width-percent: 1000;, as that is pretty buggy (especially in Outlook 2013).

The width of the <v:rect> element needs to match the width of its parent element.

Body gradient

We can also add a VML gradient to the body of the email.

To achieve this, we:

1. create a <div> that wraps our template: this will be used as the solid background color fallback
2. place the VML code immediately inside that div, basically wrapping our entire template. Note how we’re using mso-width-percent: 1000; instead of a fixed width on the <v:rect>

Here’s an example:

emails/example.html

<x-main>
  <div class="bg-gray-200">
    <!--[if gte mso 9]>
    <v:rect xmlns:v="urn:schemas-microsoft-com:vml" fill="true" stroke="false" style="mso-width-percent:1000;">
    <v:fill type="gradient" color="#edf2f7" color2="#cbd5e0" />
    <v:textbox style="mso-fit-shape-to-text:true" inset="0,0,0,0">
    <div><![endif]-->
    <table class="w-full font-sans">
      <tr>
        <td align="center" class="bg-gradient-t-gray-400">
          <!-- your content here... -->
        </td>
      </tr>
    </table>
    <!--[if gte mso 9]></div></v:textbox></v:rect><![endif]-->
  </div>
</x-main>

You can see both examples in the project repository.

Avoid inlining

Most email clients that support CSS gradients also support @media queries.

We can register a screen breakpoint to prevent Juice from inlining our gradient:

tailwind.config.js

module.exports = {
  theme: {
    screens: {
      sm: {max: '600px'},
      xs: {max: '425px'},
      screen: {raw: 'screen'},
    }
  }
}

We can then write the utility class like this:

emails/example.html

<x-main>
  <table class="w-full">
    <tr>
      <td class="bg-gray-200 screen:bg-gradient-b-black">
        <!-- ... -->
      </td>
    </tr>
  </table>
</x-main>

Resources

• tailwindcss-gradients plugin
• GitHub repository for this tutorial