gatsby-omni-font-loader
v2.0.2
Published
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.
Downloads
16,951
Maintainers
code_adrianReadme
- 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
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
intervalandtimeoutoptions - 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!