Community Plugin
View plugin on GitHub
See starters using this

Gatsby Omni Font Loader

Performant asynchronous font loading plugin for Gatsby.

  • 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


npm install --save-dev gatsby-omni-font-loader


yarn add --dev gatsby-omni-font-loader


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

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

  /* Plugin options */
  options: {

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

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

    /* Font listener interval (in ms). Default is 300ms. Recommended: >=300ms */
    interval: 300,

    /* 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. */
    timeout: 30000,

    /* 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: "",

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]--loaded.

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--loaded wf-font-awesome-5-brands--loaded wf-font-awesome-5-free--loaded wf-staatliches--loaded wf-henny-penny--loaded">
FOUT example

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!


The project is created and maintained by Adrian Bece with the generous help of community contributors. If you have used the plugin and would like to contribute, feel free to Buy Me A Coffee.

Buy Me A Coffee