Custom fonts

To add a custom font and generate @font-face rules in built CSS file we recommend using PostCSS plugin: Font Magician. Before configuring Font Magician, font files need to be included in the build process.

Font files setup

Font files should be placed in theme-name/assets/fonts. There are multiple web oriented font file formats. For majority of browsers only .woff format is enough (having it alongisde .woff2 is even better), but if you plan to support older browsers (e.g. IE 10 and older) you must include .eot and .svg formats, as well.

Fonts, and all of their variations, need to be included in index.js file inside the /fonts directory:

import './Font-Name-Variation.woff2';
import './Font-Name-Variation.woff';

After running the build process again, fonts will be placed in /theme-name/public directory and we can configure Font Magician to load them.

Font Magician configuration

To install Font Magician run:

npm install postcss-font-magician --save-dev

or

yarn add postcss-font-magician --dev

In the root of the theme there is already a postcss.config.js file with Autoprefixer enabled. To configure Font Magician it needs to be imported first and its configuration needs to be added to the existing one.

...
const postcssFontMagician = require('postcss-font-magician');

module.exports = {
  plugins: [
    ... // other postCss configs
    postcssFontMagician({
      foundries: ['custom'],
      custom: {
        FontName: { // font-family declaration
          variants: {
            normal: { // font-style variation
              400: { // font-weight variation
                url: {
                  woff: 'Font-Name-Variation.woff',
                  woff2: 'Font-Name-Variation.woff2',
                },
              },
              ... // other font-weight variation of the same font-tyle
            },
            ... // other font-style variation of the same font-family
          },
        },
        ... // other font-family declarations
      },
    }),
  ],
};

There are other configuration options for including custom fonts using Font Magician and you can check them in the font magician documentation

Restart the build process to generate @font-face rules.

Using the custom font

To use the custom font in a theme, simply declare a new font-family rule and assign it to the font name from the Font Magician configuration. A better approach would be to save the specific font-family values to variables that can be reused:

// Variable declared in a global variables .scss file.
$base-font-family: `FontName`, sans-serif,

// Using the variable in .scss partial
body {
  font-family: $base-font-family;
  ...
}