Using custom web fonts in Maizzle email templates

Last updated: May 30, 2022

It's super easy to use Google Fonts in your Maizzle email templates, but what if you need to use a custom web font?

Maybe your brand uses a custom font that isn't available through Google Fonts, or maybe you're just developing Shopify notification email templates (where the usual @import and <link> techniques aren't supported).

In this tutorial, you'll learn how to add your own custom fonts to emails in Maizzle.

Initial setup

First, let's scaffold a new project:

npx create-maizzle

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

Choose Yes when prompted to Install dependencies.

Once it finishes installing dependencies, open the project folder in your favorite editor.

Register @font-face

Imagine we have a display font called Barosan, which we're hosting on our website.

We'll use @font-face to register our custom font family - we can do this in the Template or in the Layout that we extend.

Add in Template

Open emails/transactional.html and add this before the <x-main> tag:

emails/transactional.html

<push name="head">
  <style>
    @font-face {
      font-family: 'Barosan';
      font-style: normal;
      font-weight: 400;
      src: local('Barosan Regular'), local('Barosan-Regular'), url(https://example.com/fonts/barosan.woff2) format('woff2');
    }
  </style>
</push>

This adds a separate <style> tag in the compiled email HTML, right after the main one.

Add in Layout

If you prefer a single <style> tag in your email template, you can register the font in the Layout instead. Open layouts/main.html and update the <style> tag:

layouts/main.html

   <style>
     @font-face {
       font-family: 'Barosan';
       font-style: normal;
       font-weight: 400;
       src: local('Barosan Regular'), local('Barosan-Regular'), url(https://example.com/fonts/barosan.woff2) format('woff2');
     }

     @tailwind components;
     @tailwind utilities;
   </style>

You can use the same technique to load font files from Google Fonts - it's currently the only way to get them working in Shopify notifications. To find out the URL of a Google Font (and actually, its entire `@font-face` CSS) simply access the URL they give you, in a new browser tab.

Tailwind CSS utility

Now that we're importing the font, we should register a Tailwind CSS utility for it.

Open tailwind.config.js, scroll down to fontFamily, and add a new font:

tailwind.config.js

export default {
  theme: {
    extend: {
      fontFamily: {
        barosan: ['Barosan', '-apple-system', '"Segoe UI"', 'sans-serif'],
      }
    },
  },
}

Of course, you can change the other fonts in the stack. For example, display fonts often fallback to cursive.

Great! We're now ready to use the utility class in our email template.

Quick use

Add the font-barosan class on elements that you want to use your custom font.

For example, you can add it on a heading:

<h2 class="font-barosan">An article title</h2>

With CSS inlining enabled, that would result in:

<h2 style="font-family: Barosan, -apple-system, 'Segoe UI', sans-serif;">An article title</h2>

Advanced use

Repeatedly writing that font-barosan class on all elements isn't just impractical, it also increases HTML file size (especially when inlining), which then leads to Gmail clipping.

font-family is inherited, which means you can just add the utility to the top element:

emails/transactional.html

<x-main>
  <table class="font-barosan">
    <!-- your email HTML... -->
  </table>
</x-main>

However, that could trigger Outlook's Times New Roman bug.

We can work around that by making use of Tailwind's screen variants and an Outlook font-family fallback to reduce bloat and write less code 👌

First, let's register a new @media query - we will call it screen:

tailwind.config.js

export default {
  theme: {
    screens: {
      sm: {max: '600px'},
      xs: {max: '425px'},
      screen: {raw: 'screen'},
    }
  }
}

We can now use it on the outermost¹ element:

emails/transactional.html

<x-main>
  <table class="screen:font-barosan">
    <!-- your email HTML... -->
  </table>
</x-main>

¹ Don't add it to the <body> - some email clients remove or replace this tag.

This will tuck the font-family away in an @media query:

/* Compiled CSS. Maizzle replaces escaped \: with - */
@media screen {
  .screen-font-barosan {
    font-family: Barosan, -apple-system, "Segoe UI", sans-serif !important;
  }
}

Since Outlook on Windows doesn't read @media queries, define a fallback² for it in the <head> of your Layout:

layouts/main.html

<!--[if mso]>
<style>
  td,th,div,p,a,h1,h2,h3,h4,h5,h6 {font-family: "Segoe UI", sans-serif;}
</style>
<![endif]-->

² The Maizzle Starter includes this fallback in the main.html Layout by default.

Outlook bugs

Custom fonts aren't supported in Outlook 2007-2019 on Windows - most of these email clients will fallback to Times New Roman if you try to use one.

To avoid this, you can wrap the @font-face declaration in a @media query, so that Outlook will ignore it:

@media screen {
  @font-face {
    font-family: 'Barosan';
    font-style: normal;
    font-weight: 400;
    src: local('Barosan Regular'), local('Barosan-Regular'), url(https://example.com/fonts/barosan.woff2) format('woff2');
  }
}

Also, note that font-family isn't inherited on child elements in Outlook.

Extra weights

If your font comes with dedicated files for other weights, don't just slap font-bold on an element.

Instead, import both the regular and bold versions of your font:

@font-face {
  font-family: 'Barosan';
  font-style: normal;
  font-weight: 400;
  src: local('Barosan Regular'), local('Barosan-Regular'), url(https://example.com/fonts/barosan.woff2) format('woff2');
}

@font-face {
  font-family: 'Barosan';
  font-style: normal;
  font-weight: 700;
  src: local('Barosan Bold'), local('Barosan-Bold'), url(https://example.com/fonts/barosan-bold.woff2) format('woff2');
}

Resources

The Ultimate Guide to Web Fonts on Litmus
@font-face support in email