--- title: "Providers" description: "Font providers are designed to be pluggable and extensible, so no matter your setup you should be able to use an existing provider or write your own." canonical_url: "https://nuxt.com/modules/fonts/providers" --- # Providers > Font providers are designed to be pluggable and extensible, so no matter your setup you should be able to use an existing provider or write your own. ## Built-In Providers Nuxt Fonts ships with a number of built-in providers. ### `local` The local provider deeply scans your `public/` directories (including of your layers) for font files (supporting `ttf`, `woff`, `woff2`, `eot` or `otf` extensions). Directories that modules add to `nitro.publicAssets` are not scanned; add them to [`local.dirs`](#fonts-installed-from-npm) to use the fonts within. Then, when you use a `font-family` in your CSS, we check to see whether it matches one of these files. By default, we expect the font file to be the `400` weight, `normal` style, and `latin` subset. To indicate different weights and styles, please include that information in the filename. For example `comic-sans-ms.woff2` (400/normal/latin; defaults), `comic-sans-ms-700-italic-cyrillic.woff2` (700/italic/cyrillic), or for variable fonts `comic-sans-ms-100-900.woff2` (100 900/normal/latin). Named weights are accepted in place of a weight number: `comic-sans-ms-bold.woff2`. `font-family` values with spaces and/or caps will lookup hyphenated lowercase filenames as well, eg `font-family: 'Comic Sans MS'` will look for `comic-sans-ms.woff2` as well as `Comic\ Sans\ MS.woff2` on disk. #### Named weights The following names are recognised, both in filenames and in the `weights` you configure. Hyphenated and unhyphenated spellings are equivalent, so `comic-sans-ms-semibold.woff2` and `comic-sans-ms-semi-bold.woff2` both resolve to `600`. `normal` and `regular` are only read from your configuration. A file is `400` unless its name says otherwise, and a trailing word is dropped when looking for the family, so `comic-sans-ms-regular.woff2` resolves `font-family: 'Comic Sans MS'` at `400` regardless. | Weight | Names | | ------ | -------------------------------------------------------- | | `100` | `thin`, `hairline` | | `200` | `extra-light`, `extralight`, `ultra-light`, `ultralight` | | `300` | `light` | | `400` | `normal`, `regular` | | `500` | `medium` | | `600` | `semi-bold`, `semibold`, `demi-bold`, `demibold` | | `700` | `bold` | | `800` | `extra-bold`, `extrabold`, `ultra-bold`, `ultrabold` | | `900` | `black`, `heavy` | #### Variable fonts A filename can declare a variable weight range as two CSS weights, separated by a space, hyphen or dot: `my-font-100 900.woff2`, `my-font-100-900.woff2` or `my-font.100-900.woff2` are all read as covering `100` to `900`. Both bounds have to be recognised weights (a multiple of 100 between 100 and 900) in ascending order, so `my-font-300-234987akd.woff2` is still read as a single `300` weight. Such a file will be used for any weight or weight range inside the declared range, so `my-font-100-900.woff2` matches `weights: [400]`, `weights: ['400 700']` and `weights: ['100 900']` alike. When no file covers the whole of a requested range, the endpoints of that range are looked up as static weights instead, so a project shipping `my-font.woff2` and `my-font-bold.woff2` resolves the default `weights: ['400 700']` as two separate `@font-face` rules. Files marked as variable without a range (`my-font-variable.woff2`, `my-font-vf.woff2`, or a camel-cased `MyFontVariable.woff2` / `MyFontVF.woff2`) are treated as covering the full `100` to `900` range. The marker is also treated as part of the family name, so `faro-variable.woff2` matches both `font-family: 'Faro Variable'` and `font-family: 'Faro'`, and `CalSansVF.woff2` matches both `font-family: 'CalSansVF'` and `font-family: 'CalSans'`. ::warning{to="https://nuxt.com/modules/fonts/configuration#font-options"} Please note that the local provider will only attempt to load styles and weights that were configured in the *Font Options*. :: #### Fonts installed from npm Some fonts are distributed as npm packages containing bare font files, with no stylesheet for the [`npm` provider](#npm) to read. If one of these is installed, it is scanned automatically and needs no configuration: ```ts export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ { name: 'Geist', provider: 'local' }, ], } }) ``` Filenames still drive weight, style and subset detection, so `Geist-Bold.woff2` resolves `font-family: Geist` at weight `700`. Matched fonts are emitted as build assets and served from your own origin. For a package that is not scanned automatically, add it with `packages`, or point at a directory directly with `dirs` (relative paths are resolved from your project root): ```ts export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { local: { packages: ['my-font-package'], dirs: ['assets/fonts'], }, } }) ``` ### `google` [Google Fonts](https://fonts.google.com/) is one of the best known public font APIs. ### `googleicons` [Google Fonts Icons](https://fonts.google.com/icons) adds support for Material Symbols and Material Icons. ### `bunny` [Bunny Fonts](https://fonts.bunny.net/) is provided by [bunny.net](https://bunny.net/) and is a drop-in Google Fonts compatible API, focusing on privacy. ### `fontshare` [Fontshare](https://www.fontshare.com/) is a free font service with 100+ professional-grade fonts from the Indian Type Foundry (ITF). ::warning{to="https://www.fontshare.com/licenses/itf-ffl"} You should read their terms in full before using a font through `fontshare`. :: ### `fontsource` [Fontsource](https://fontsource.org/docs/getting-started/introduction) is a collection of open-source fonts that are designed for self-hosting in web applications. ### `npm` The npm provider resolves fonts from npm packages installed in your project's `node_modules`. It automatically detects known font packages (such as [`@fontsource/*`](https://fontsource.org/), [`@fontsource-variable/*`](https://fontsource.org/), and [`cal-sans`](https://github.com/calcom/font)) from your `package.json` dependencies and devDependencies. By default the stylesheet shipped with the package is read from disk (`remote: false`) rather than from a CDN, and the font files it references are read from the installed package and served from your own origin. Only packages that ship a CSS entrypoint (such as `@fontsource/*` or `cal-sans`) can be used with this provider. Packages that ship bare font files are handled by the [`local` provider](#local) instead. ::note{to="https://nuxt.com/modules/fonts/configuration#provider"} Setting a top-level `provider` disables every other provider, including `npm`, so a per-family `provider: 'npm'` will not be used. :: ```ts export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ // Automatically resolved if @fontsource/roboto is in your package.json { name: 'Roboto', provider: 'npm' }, // Variable fonts are also supported { name: 'Inter Variable', provider: 'npm' }, ], } }) ``` ### `adobe` [Adobe Fonts](https://fonts.adobe.com/) is a font service for both personal and commercial use included with Creative Cloud subscriptions. To configure the Adobe provider in your Nuxt app, you must provide a Project ID or array of Project IDs corresponding to the Web Projects you have created in Adobe Fonts. ```ts export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { adobe: { id: ['', ''], }, } }) ``` ::warning We currently can't provide non-latin subsets for Adobe Fonts as they do not have a public API for that. Please use other providers in such cases. :: ::warning{to="https://www.adobe.com/legal/terms.html"} You should read their terms in full before using a font through `adobe`. :: ## Custom Providers The core of the provider API in Nuxt Fonts has been extracted to a common library that can be used by any framework - [`unifont`](https://github.com/unjs/unifont). The provider API is likely to evolve in the next few releases of `unifont`, but at the moment it looks like this: ```ts import { defineFontProvider } from 'unifont' export default defineFontProvider('some-custom-provider', async (options) => { // do some setup return { async resolveFont (fontFamily, options) { if (fontFamily === 'My Font Family') { return { fonts: [ { src: [ { url: 'https://cdn.org/my-font.woff2', format: 'woff2' }, ], weight: 400, style: 'normal', } ] } } } } }) ``` Module authors can also add their own providers (or remove existing ones) in the `fonts:providers` hook which is called by Nuxt Fonts after all modules have run. ```ts nuxt.hook('fonts:providers', providers => { delete providers.adobe providers['custom-provider'] = defineFontProvider('custom-provider', async () => { /** some setup */ return { async resolveFont (fontFamily, options) { /** resolve font faces */ } } }) }) ``` ## Sitemap See the full [sitemap](https://nuxt.com/sitemap.md) for all pages.