# gatsby-plugin-webfonts > A Gatsby plugin to handle cdn, base64 and self hosted webfonts Latest version **2.3.2** (published 2022-12-27) · MIT license · 0 weekly downloads ## Install ```sh npm install gatsby-plugin-webfonts pnpm add gatsby-plugin-webfonts yarn add gatsby-plugin-webfonts bun add gatsby-plugin-webfonts ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 2.3.2 | | Published | 2022-12-27 | | First published | 2019-05-03 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 6 | | Unpacked size | 38 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 54 | | Maintainers | hupe1980 | | Keywords | gatsby-plugin, gatsby, plugin, web, fonts, loader, google, webfonts, webfontloader | ## Links - npm: https://www.npmjs.com/package/gatsby-plugin-webfonts - Repository: https://github.com/hupe1980/gatsby-plugin-webfonts - Homepage: https://github.com/hupe1980/gatsby-plugin-webfonts#readme - Issues: https://github.com/hupe1980/gatsby-plugin-webfonts/issues - npm.io page: https://npm.io/package/gatsby-plugin-webfonts ## Dependencies (6) - [axios](https://npm.io/package/axios.md) ^1.2.1 - [cssnano](https://npm.io/package/cssnano.md) ^5.1.14 - [postcss](https://npm.io/package/postcss.md) ^8.4.19 - [fs-extra](https://npm.io/package/fs-extra.md) ^11.1.0 - [postcss-js](https://npm.io/package/postcss-js.md) ^4.0.0 - [lodash.isempty](https://npm.io/package/lodash.isempty.md) ^4.4.0 ## Alternatives - [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads - [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads - [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads - [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads - [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads ## Recent versions - 2.3.2 (latest) — 2022-12-27 - 2.3.1 — 2022-12-11 - 2.3.0 — 2022-12-10 - 2.2.2 — 2022-04-05 - 2.2.1 — 2021-11-16 - 2.2.0 — 2021-11-14 - 2.1.1 — 2021-07-22 - 2.1.0 — 2021-03-27 - 2.0.0 — 2021-03-04 - 1.1.4 — 2021-01-06 - 1.1.3 — 2020-06-17 - 1.1.2 — 2020-01-05 - 1.1.1 — 2019-12-17 - 1.1.0 — 2019-07-26 - 1.0.12 — 2019-06-17 - … 14 more at https://npm.io/package/gatsby-plugin-webfonts/versions ## README # gatsby-plugin-webfonts > A [Gatsby](https://github.com/gatsbyjs/gatsby) plugin to handle cdn, base64 and self hosted webfonts - Creates minified @font-face CSS rules - Supports font-display property (Default: 'swap') - Handles preconnect and preload optimizations - Automatically downloads fonts for self hosting - Supports cdn, base64 and self hosted Fonts (Default: 'selfHosted') - Supports header user-agent for specific font type ## Install ```sh // with npm npm install gatsby-plugin-webfonts // with yarn yarn add gatsby-plugin-webfonts ``` ## How to use Edit `gatsby-config.js` ```javascript module.exports = { plugins: [ { resolve: `gatsby-plugin-webfonts`, options: { fonts: { google: [ { family: "Roboto", // 'font-family' property variants: ["300", "400", "500"], //subsets: ['latin'], //text: 'Hello', //fontDisplay: 'swap' || 'auto' || 'block' || 'fallback' || 'optional', //strategy: 'selfHosted' || 'base64' || 'cdn', // Other properties as per https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face (except 'src' & 'font-family') can go here i.e. //[cssProperty]: 'value', }, ], selfHosted: [ { family: "Open Sans", urls: { woff2: `/font/OpenSans400.woff2`, woff: `/font/OpenSans400.woff`, //[format]: '/[filepath]/[filename], }, //[cssProperty]: 'value', }, ], }, // formatAgents: { // eot: `Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.1; WOW64; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; .NET4.0C; .NET4.0E)`, // ttf: `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/534.59.8 (KHTML, like Gecko) Version/5.1.9 Safari/534.59.8`, // woff: `Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; .NET4.0C; .NET4.0E; .NET CLR 2.0.50727; .NET CLR 3.0.30729; .NET CLR 3.5.30729; rv:11.0) like Gecko`, // woff2: `Mozilla/5.0 (Windows NT 10.0; Win64; x64; ServiceUI 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.79 Safari/537.36 Edge/14.14393`, // }, //formats: ['woff2', 'woff', 'otf', 'ttf'], //useMinify: true, //usePreload: true, //usePreconnect: false, }, }, ], }; ``` ## Google Fonts Using [Google's Font API](https://code.google.com/apis/webfonts/docs/getting_started.html), name the font families you'd like to load. ```javascript module.exports = { plugins: [ { resolve: `gatsby-plugin-webfonts`, options: { fonts: { google: [ { family: "Roboto", variants: ["300", "400", "500"], }, { family: "Open Sans Condensed", variants: ["300", "700"], }, ], }, }, }, ], }; ``` You can also supply the text parameter or array of subsets to perform character subsetting: ```javascript module.exports = { plugins: [ { resolve: `gatsby-plugin-webfonts`, options: { fonts: { google: [ { family: "Roboto", variants: ["300", "400", "500"], text: "Hello", }, { family: "Roboto", variants: ["300", "400", "500"], subsets: ["latin", ""], }, ], }, }, }, ], }; ``` Pass you user-agent for specific font type: ```javascript module.exports = { plugins: [ { resolve: `gatsby-plugin-webfonts`, options: { fonts: { google: [ { family: "Roboto", variants: ["300", "400", "500"], }, ], }, formatAgents: { woff: `Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; .NET4.0C; .NET4.0E; .NET CLR 2.0.50727; .NET CLR 3.0.30729; .NET CLR 3.5.30729; rv:11.0) like Gecko`, woff2: `Mozilla/5.0 (Windows NT 10.0; Win64; x64; ServiceUI 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.79 Safari/537.36 Edge/14.14393`, }, }, }, ], }; ``` The text subsetting functionality is only available for Google fonts. ### Google Fonts v2 > This is an extension of the "Google Fonts" setting which uses the latest API. You can also use the latest [Google Fonts API v2](https://developers.google.com/fonts/docs/css2). Use the `axes` option like so: ```javascript module.exports = { plugins: [ { resolve: `gatsby-plugin-webfonts`, options: { fonts: { google2: [ { family: "Roboto", axes: "wght@300;400;500", }, ], }, }, }, ], }; ``` A [variable font](https://web.dev/variable-fonts/) packs all the styles and weights of a font family into a single file. Only a few Google Fonts are available as [variable fonts](https://fonts.google.com/variablefonts). Some have their own custom axes that can be set accordingly. ```javascript module.exports = { plugins: [ { resolve: `gatsby-plugin-webfonts`, options: { fonts: { google2: [ { family: "Rubik", axes: "wght@300..600", // multiple ranges are supported, ex: "wght@300..500;700..900" }, ], }, }, }, ], }; ``` ## Self Hosted Fonts Add your own self hosted font files. The plugin will handle the imports & preloading. Strategy is always `selfHosted`, subsets are already defined within your font file. ```javascript module.exports = { plugins: [ { resolve: `gatsby-plugin-webfonts`, options: { fonts: { selfHosted: [ { family: "Open Sans", urls: { // src attributes // path relative to gatsby project root woff2: `/examplePath/filename.woff2`, woff: `/examplePath/filename.woff`, otf: `/examplePath/filename.otf`, ttf: `/examplePath/filename.ttf`, }, fontStyle: "light", fontWeight: 300, }, ], }, }, }, ], }; ``` As per gatsby docs it is recommended not to put fonts in the `/static` directory. This plugin will automatically be copy them across to `/public/webfonts/selfHosted`. ## License [MIT](LICENSE) --- _Source: https://npm.io/package/gatsby-plugin-webfonts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._