{"id":13727104,"url":"https://github.com/codeAdrian/gatsby-omni-font-loader","last_synced_at":"2025-05-07T22:30:51.045Z","repository":{"id":43192628,"uuid":"308862131","full_name":"codeAdrian/gatsby-omni-font-loader","owner":"codeAdrian","description":"Font loader optimized for maximum performance. Removes render-blocking font resources and loads them asynchronusly. Handle FOUT \u0026 FOUC with font loading status watcher. Supports both local-hosted fonts and web fonts.","archived":false,"fork":false,"pushed_at":"2022-11-23T03:05:23.000Z","size":41,"stargazers_count":107,"open_issues_count":9,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-06T07:34:10.037Z","etag":null,"topics":["css","font","gatsby","react","reactjs","web-fonts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeAdrian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-31T11:02:51.000Z","updated_at":"2025-02-18T21:18:02.000Z","dependencies_parsed_at":"2023-01-22T00:18:11.379Z","dependency_job_id":null,"html_url":"https://github.com/codeAdrian/gatsby-omni-font-loader","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeAdrian%2Fgatsby-omni-font-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeAdrian%2Fgatsby-omni-font-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeAdrian%2Fgatsby-omni-font-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeAdrian%2Fgatsby-omni-font-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeAdrian","download_url":"https://codeload.github.com/codeAdrian/gatsby-omni-font-loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252965212,"owners_count":21832839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","font","gatsby","react","reactjs","web-fonts"],"created_at":"2024-08-03T01:03:39.600Z","updated_at":"2025-05-07T22:30:50.344Z","avatar_url":"https://github.com/codeAdrian.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://res.cloudinary.com/dazdt97d3/image/upload/c_scale,q_auto:best,w_200/v1606558223/omni-logo.jpg\" alt=\"Omni font loader logo\"\u003e\n\u003cbr/\u003e\u003cbr/\u003e\n\u003ch1\u003eGatsby Omni Font Loader v2\u003c/h1\u003e\n\u003c/div\u003e\n\n- Simple way to add webfonts or custom fonts to Gatsby project\n- Performant asynchronous font loading can be enabled\n- Font loading listener can be enabled\n- Flash Of Unstyled Text (FOUT) handling support\n\n\u003cdiv align=\"center\"\u003e\n\u003cbr/\u003e\n\u003cimg src=\"https://badgen.net/github/tag/codeAdrian/gatsby-omni-font-loader\" /\u003e \u003cimg src=\"https://badgen.net/npm/dt/gatsby-omni-font-loader\" /\u003e \u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\" /\u003e\n\u003cbr/\u003e\u003cbr/\u003e\n\n\u003cimg src=\"https://badgen.net/github/stars/codeAdrian/gatsby-omni-font-loader\" /\u003e \u003cimg src=\"https://badgen.net/github/open-issues/codeAdrian/gatsby-omni-font-loader\" /\u003e \u003cimg src=\"https://badgen.net/github/closed-issues/codeAdrian/gatsby-omni-font-loader\" /\u003e \u003cimg src=\"https://badgen.net/github/last-commit/codeAdrian/gatsby-omni-font-loader/main\" /\u003e \u003cimg src=\"https://badgen.net/github/license/codeAdrian/gatsby-omni-font-loader\" /\u003e \u003cimg src=\"https://badgen.net/packagephobia/install/gatsby-omni-font-loader\" /\u003e\n\n\u003c/div\u003e\n\u003cbr/\u003e\u003cbr/\u003e\n\n## Features\n\n- Supports web fonts \u0026 self-hosted fonts\n- Preloads the files \u0026 preconnects to the URL\n- Loads fonts asynchronously to avoid render blocking\n- Implemented with [fast loading snippets](https://csswizardry.com/2020/05/the-fastest-google-fonts/)\n- Loading status listener for avoiding FOUT\n- Small size \u0026 minimal footprint\n\n## Install\n\n`npm install gatsby-omni-font-loader react-helmet`\n\nor\n\n`yarn add gatsby-omni-font-loader react-helmet`\n\n## Configuration\n\nAdd the following snippet to `gatsby-config.js` plugins array.\n\n```js\n{\n  /* Include plugin */\n  resolve: \"gatsby-omni-font-loader\",\n\n  /* Plugin options */\n  options: {\n\n    /* Font loading mode */\n    mode: \"async\",\n\n    /* Enable font loading listener to handle FOUT */\n    enableListener: true,\n\n    /* Preconnect URL-s. This example is for Google Fonts */\n    preconnect: [\"https://fonts.gstatic.com\"],\n\n    /* Self-hosted fonts config. Add font files and font CSS files to \"static\" folder */\n    custom: [\n      {\n        /* Exact name of the font as defied in @font-face CSS rule */\n        name: [\"Font Awesome 5 Brands\", \"Font Awesome 5 Free\"],\n        /* Path to the font CSS file inside the \"static\" folder with @font-face definition */\n        file: \"/fonts/fontAwesome/css/all.min.css\",\n      },\n    ],\n\n    /* Web fonts. File link should point to font CSS file. */\n    web: [{\n        /* Exact name of the font as defied in @font-face CSS rule */\n        name: \"Staatliches\",\n        /* URL to the font CSS file with @font-face definition */\n        file: \"https://fonts.googleapis.com/css2?family=Staatliches\",\n      },\n    ],\n  },\n}\n```\n\n## Options\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eOption\u003c/th\u003e\n      \u003cth\u003eDescription\u003c/th\u003e\n      \u003cth\u003eDefault\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n  \u003ctr\u003e\n      \u003ctd\u003emode\u003c/td\u003e\n      \u003ctd\u003eCan be set to \u003ccode\u003easync\u003c/code\u003e (default) or \u003ccode\u003erender-blocking\u003c/code\u003e. In \u003ccode\u003easync\u003c/code\u003e mode, fonts are loaded in optimal way, but FOUT is visible. In \u003ccode\u003erender-blocking\u003c/code\u003e mode FOUT will happen in rare cases, but the font files will become render-blocking.\u003c/td\u003e\n      \u003ctd\u003easync\u003c/td\u003e\n  \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003escope\u003c/td\u003e\n      \u003ctd\u003eCan be set to \u003ccode\u003ebody\u003c/code\u003e (default) or \u003ccode\u003ehtml\u003c/code\u003e. Sets the target element for HTML classnames to be applied to.\u003c/td\u003e\n      \u003ctd\u003ebody\u003c/td\u003e\n  \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eenableListener\u003c/td\u003e\n      \u003ctd\u003eWorks in \u003ccode\u003easync\u003c/code\u003e 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.\u003c/td\u003e\n      \u003ctd\u003efalse\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003einterval \u003cstrong\u003e(V1 ONLY)\u003c/strong\u003e\u003c/td\u003e\n      \u003ctd\u003eWorks if \u003ccode\u003eenableListener\u003c/code\u003e is \u003ccode\u003etrue\u003c/code\u003e. Font listener interval (in ms). Default is 300ms. Recommended: \u003e=300ms. \u003c/td\u003e\n      \u003ctd\u003e300\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003etimeout \u003cstrong\u003e(V1 ONLY)\u003c/strong\u003e\u003c/td\u003e\n      \u003ctd\u003eWorks if \u003ccode\u003eenableListener\u003c/code\u003e is \u003ccode\u003etrue\u003c/code\u003e. 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.\u003c/td\u003e\n      \u003ctd\u003e30000\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003ecustom\u003c/td\u003e\n      \u003ctd\u003eSelf-hosted fonts config. Add font files and font CSS files to \u003ccode\u003estatic\u003c/code\u003e folder. Array of \u003ccode\u003e{name: \"Font name\", file: \"https://url-to-font-css.path\"}\u003c/code\u003e objects.\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003e[]\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eweb\u003c/td\u003e\n      \u003ctd\u003eWeb fonts config. File link should point to font CSS file. Array of \u003ccode\u003e{name: \"Font name\", file: \"https://url-to-font-css.path\"}\u003c/code\u003e objects.\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003e[]\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003epreconnect\u003c/td\u003e\n      \u003ctd\u003eURLs used for preconnect meta. Base URL where \u003cstrong\u003efont files\u003c/strong\u003e are hosted.\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003e[]\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003epreload\u003c/td\u003e\n      \u003ctd\u003eAdditional URLs used for preload meta. Preload for URLs provided under \u003ccode\u003efile\u003c/code\u003e attribute of \u003ccode\u003ecustom\u003c/code\u003e and \u003ccode\u003eweb\u003c/code\u003e fonts are automatically generated.\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003e[]\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003ctbody\u003e\n\u003c/table\u003e\n\n## Async mode vs Render-blocking mode\n\n### Async mode\n\nLoad 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.\n\n**Pros:** Performance, content is displayed before font files are downloaded and parsed\n\u003cbr/\u003e\n**Cons:** FOUT needs to be handled\n\n### Render-blocking mode\n\nLoad 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.\n\n**Pros:** Simple markup, FOUT won't occur in most cases\n\u003cbr/\u003e\n**Cons:** Font stylesheets and font files can delay first content paint time\n\n## Handling FOUT with Font loading listener\n\nWhen loading fonts asynchronously, Flash Of Unstyled Text (FOUT) might happen because fonts load few moments later after page is displayed to the user.\n\nTo 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.\n\nWhen `enableListener: true` is set in plugin config in `gatsby-config.js`, HTML classes are being added to `\u003cbody\u003e` element as the fonts are being loaded.\n\nHTML class name format will be in the following format `wf-[font-family-name]`. When all fonts are loaded `wf-all` is applied.\n\nYou can use the [Font Style Matcher](https://meowni.ca/font-style-matcher/) to adjust the perfect fallback font and fallback CSS config.\n\nHere is the example of how `body` element will look like after all fonts are being loaded (depending on the config).\n\n```html\n\u003cbody\n  class=\"wf-lazy-monday wf-font-awesome-5-brands wf-font-awesome-5-free wf-staatliches wf-all\"\n\u003e\u003c/body\u003e\n```\n\n\u003cimg alt=\"FOUT example\" src=\"https://res.cloudinary.com/dazdt97d3/image/upload/v1604140006/fouc.gif\"\u003e\n\n## V2 breaking changes\n* Removed `interval` and `timeout` options\n* Changed class name format to a more generic `wf-[font-family-name]` to avoid mixing naming conventions\n\n## Issues and Contributions\n\nFeel 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.\n\nContributions are welcome and appreciated!\n\n## Code contributors\n\nThank you for your contribution!\n\n[Henrik](https://github.com/henrikdahl) • [Lennart](https://github.com/LekoArts) • [Francis Champagne](https://github.com/fcisio) • [Hugo](https://github.com/hugofabricio)\n\n## Supported by\n\nThank you for your support!\n\n[Roboto Studio](https://roboto.studio/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FcodeAdrian%2Fgatsby-omni-font-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FcodeAdrian%2Fgatsby-omni-font-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FcodeAdrian%2Fgatsby-omni-font-loader/lists"}