Community Plugin

gatsby-plugin-webfonts

A Gatsby plugin to handle cdn, base64 and self hosted webfonts

Creates minified @font-face CSS rules
Supports font-display property (Default: ‘swap’)
Handles preconnect and preload optimizations
Automatically downloads fonts for self hosting
Supports cdn, base64 and self hosted Fonts (Default: ‘selfHosted’)
Supports header user-agent for specific font type

Install

// with npm
npm install gatsby-plugin-webfonts

// with yarn
yarn add gatsby-plugin-webfonts

How to use

Edit gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-webfonts`,
      options: {
        fonts: {
          google: [
            {
              family: "Roboto",
              variants: ["300", "400", "500"],
              //subsets: ['latin']
              //text: 'Hello'
              //fontDisplay: 'swap',
              //strategy: 'selfHosted' // 'base64' || 'cdn'
            },
          ],
        },
        // formatAgents: {
        //   eot: `Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.1; WOW64; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; .NET4.0C; .NET4.0E)`,
        //   ttf: `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/534.59.8 (KHTML, like Gecko) Version/5.1.9 Safari/534.59.8`,
        //   woff: `Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; .NET4.0C; .NET4.0E; .NET CLR 2.0.50727; .NET CLR 3.0.30729; .NET CLR 3.5.30729; rv:11.0) like Gecko`,
        //   woff2: `Mozilla/5.0 (Windows NT 10.0; Win64; x64; ServiceUI 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.79 Safari/537.36 Edge/14.14393`,
        // },
        //formats: ['woff2', 'woff'],
        //useMinify: true,
        //usePreload: true,
        //usePreconnect: false,
      },
    },
  ],
};

Google Fonts

Using Google’s Font API, name the font families you’d like to load.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-webfonts`,
      options: {
        fonts: {
          google: [
            {
              family: "Roboto",
              variants: ["300", "400", "500"],
            },
            {
              family: "Open Sans Condensed",
              variants: ["300", "700"],
            },
          ],
        },
      },
    },
  ],
};

You can also supply the text parameter to perform character subsetting:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-webfonts`,
      options: {
        fonts: {
          google: [
            {
              family: "Roboto",
              variants: ["300", "400", "500"],
              text: "Hello",
            },
          ],
        },
      },
    },
  ],
};

Pass you user-agent for specific font type:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-webfonts`,
      options: {
        fonts: {
          google: [
            {
              family: "Roboto",
              variants: ["300", "400", "500"],
            },
          ],
        },
        formatAgents: {
          woff: `Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; .NET4.0C; .NET4.0E; .NET CLR 2.0.50727; .NET CLR 3.0.30729; .NET CLR 3.5.30729; rv:11.0) like Gecko`,
          woff2: `Mozilla/5.0 (Windows NT 10.0; Win64; x64; ServiceUI 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.79 Safari/537.36 Edge/14.14393`,
        },
      },
    },
  ],
};

The text subsetting functionality is only available for Google fonts.

Google Fonts v2

This is an extension of the “Google Fonts” setting which uses the latest API.

You can also use the latest Google Fonts API v2.

Use the axes option like so:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-webfonts`,
      options: {
        fonts: {
          google2: [
            {
              family: "Roboto",
              axes: "wght@300;400;500",
            },
          ],
        },
      },
    },
  ],
};

A variable font packs all the styles and weights of a font family into a single file.

Only a few Google Fonts are available as variable fonts. Some have their own custom axes that can be set accordingly.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-webfonts`,
      options: {
        fonts: {
          google2: [
            {
              family: "Rubik",
              axes: "wght@300..600", // multiple ranges are supported, ex: "wght@300..500;700..900"
            },
          ],
        },
      },
    },
  ],
};

License

MIT