Gatsby Omni Font Loader v2

• Simple way to add webfonts or custom fonts to Gatsby project
• Performant asynchronous font loading can be enabled
• Font loading listener can be enabled
• Flash Of Unstyled Text (FOUT) handling support

Features

• Supports web fonts & self-hosted fonts
• Preloads the files & preconnects to the URL
• Loads fonts asynchronously to avoid render blocking
• Implemented with fast loading snippets
• Loading status listener for avoiding FOUT
• Small size & minimal footprint

Install

npm install gatsby-omni-font-loader react-helmet

or

yarn add gatsby-omni-font-loader react-helmet

Configuration

Add the following snippet to gatsby-config.js plugins array.

{
  /* Include plugin */
  resolve: "gatsby-omni-font-loader",

  /* Plugin options */
  options: {

    /* Font loading mode */
    mode: "async",

    /* Enable font loading listener to handle FOUT */
    enableListener: true,

    /* Preconnect URL-s. This example is for Google Fonts */
    preconnect: ["https://fonts.gstatic.com"],

    /* Self-hosted fonts config. Add font files and font CSS files to "static" folder */
    custom: [
      {
        /* Exact name of the font as defied in @font-face CSS rule */
        name: ["Font Awesome 5 Brands", "Font Awesome 5 Free"],
        /* Path to the font CSS file inside the "static" folder with @font-face definition */
        file: "/fonts/fontAwesome/css/all.min.css",
      },
    ],

    /* Web fonts. File link should point to font CSS file. */
    web: [{
        /* Exact name of the font as defied in @font-face CSS rule */
        name: "Staatliches",
        /* URL to the font CSS file with @font-face definition */
        file: "https://fonts.googleapis.com/css2?family=Staatliches",
      },
    ],
  },
}

Options

Option	Description	Default
mode	Can be set to async (default) or render-blocking. In async mode, fonts are loaded in optimal way, but FOUT is visible. In render-blocking mode FOUT will happen in rare cases, but the font files will become render-blocking.	async
scope	Can be set to body (default) or html. Sets the target element for HTML classnames to be applied to.	body
enableListener	Works in async mode. Enable font loading listener to handle Flash Of Unstyled Text. If enabled, CSS classes will be applied to HTML once each font has finished loading.	false
interval (V1 ONLY)	Works if enableListener is true. Font listener interval (in ms). Default is 300ms. Recommended: >=300ms.	300
timeout (V1 ONLY)	Works if enableListener is true. Font listener timeout value (in ms). Default is 30s (30000ms). Listener will no longer check for loaded fonts after timeout, fonts will still be loaded and displayed, but without handling FOUT.	30000
custom	Self-hosted fonts config. Add font files and font CSS files to static folder. Array of {name: "Font name", file: "https://url-to-font-css.path"} objects.	[]
web	Web fonts config. File link should point to font CSS file. Array of {name: "Font name", file: "https://url-to-font-css.path"} objects.	[]
preconnect	URLs used for preconnect meta. Base URL where font files are hosted.	[]
preload	Additional URLs used for preload meta. Preload for URLs provided under file attribute of custom and web fonts are automatically generated.	[]

Async mode vs Render-blocking mode

Async mode

Load font stylesheets and files in low-priority mode. If you want to add fonts in a performant way, handle FOUT on your own and make sure that the page render times are low, you should use async mode.

Pros: Performance, content is displayed before font files are downloaded and parsed
Cons: FOUT needs to be handled

Render-blocking mode

Load font stylesheets and files in high-priority mode. If you want to use this plugin as a simple way to add fonts to your project as you would do in any other project, without any performance optimizations and FOUT handling, you should use render-blocking mode.

Pros: Simple markup, FOUT won't occur in most cases
Cons: Font stylesheets and font files can delay first content paint time

Handling FOUT with Font loading listener

When loading fonts asynchronously, Flash Of Unstyled Text (FOUT) might happen because fonts load few moments later after page is displayed to the user.

To avoid this, we can use CSS to style the fallback font to closely match the font size, line height and letter spacing of the main font that is being loaded.

When enableListener: true is set in plugin config in gatsby-config.js, HTML classes are being added to <body> element as the fonts are being loaded.

HTML class name format will be in the following format wf-[font-family-name]. When all fonts are loaded wf-all is applied.

You can use the Font Style Matcher to adjust the perfect fallback font and fallback CSS config.

Here is the example of how body element will look like after all fonts are being loaded (depending on the config).

<body
  class="wf-lazy-monday wf-font-awesome-5-brands wf-font-awesome-5-free wf-staatliches wf-all"
></body>

V2 breaking changes

• Removed interval and timeout options
• Changed class name format to a more generic wf-[font-family-name] to avoid mixing naming conventions

Issues and Contributions

Feel free to report issues you find and feel free to contribute to the project by creating Pull Requests.

Contributions are welcome and appreciated!

Code contributors

Thank you for your contribution!

Henrik • Lennart • Francis Champagne • Hugo

Supported by

Thank you for your support!

Roboto Studio