Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/codeAdrian/gatsby-omni-font-loader

Font loader optimized for maximum performance. Removes render-blocking font resources and loads them asynchronusly. Handle FOUT & FOUC with font loading status watcher. Supports both local-hosted fonts and web fonts.
https://github.com/codeAdrian/gatsby-omni-font-loader

css font gatsby react reactjs web-fonts

Last synced: 3 months ago
JSON representation

Host: GitHub
URL: https://github.com/codeAdrian/gatsby-omni-font-loader
Owner: codeAdrian
License: mit
Created: 2020-10-31T11:02:51.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2022-11-23T03:05:23.000Z (almost 2 years ago)
Last Synced: 2024-07-10T07:20:07.057Z (4 months ago)
Topics: css, font, gatsby, react, reactjs, web-fonts
Language: TypeScript
Homepage:
Size: 40 KB
Stars: 105
Watchers: 3
Forks: 7
Open Issues: 9
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-list - gatsby-omni-font-loader - blocking font resources and loads them asynchronusly. Handle FOUT & FOUC with font loading status watcher. Supports both local-hosted fonts and web fonts. | codeAdrian | 72 | (TypeScript)

README

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](https://csswizardry.com/2020/05/the-fastest-google-fonts/)
- Loading status listener for avoiding FOUT
- Small size & minimal footprint

## Install

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

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

## Configuration

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

```js
{
/* 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 `` 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](https://meowni.ca/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).

```html

```

FOUT example

## 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](https://github.com/codeAdrian/gatsby-omni-font-loader/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](https://github.com/henrikdahl) • [Lennart](https://github.com/LekoArts) • [Francis Champagne](https://github.com/fcisio) • [Hugo](https://github.com/hugofabricio)

## Supported by

Thank you for your support!

[Roboto Studio](https://roboto.studio/)