--- title: "Configuration" description: "Nuxt Fonts works out of the box with zero config, but you can always add some configurations for finer-grained control." canonical_url: "https://nuxt.com/modules/fonts/configuration" --- # Configuration > Nuxt Fonts works out of the box with zero config, but you can always add some configurations for finer-grained control. You do not need to configure Nuxt Fonts but you can do so for finer-grained control, with the `fonts` property in your `nuxt.config`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { // Options } }) ``` ## Font options These options define how fonts will be downloaded, including the weights, styles, subsets, etc. These options can be used as a default behaviour with [`defaults`](#defaults) or a separate behaviour for a specific font with [`families`](#families). ### `defaults` This defines the default font options for all fonts. Example of `defaults`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { defaults: { weights: ['400 700'], styles: ['normal', 'italic'], subsets: [ 'cyrillic-ext', 'cyrillic', 'greek-ext', 'greek', 'vietnamese', 'latin-ext', 'latin', ] }, } }) ``` #### `weights` Default: `['400 700']` Defines the font-weights that should be downloaded for a font. ::tip To specify a variable font weight, define the range as you would in plain CSS (for example, `100 900`). See [variable fonts](https://nuxt.com/modules/fonts/usage#variable-fonts) for how each provider handles a range. :: The [`local` provider](https://nuxt.com/modules/fonts/providers#local) also accepts named weights, in either the hyphenated or unhyphenated spelling, so `weights: ['medium', 'semibold']` is equivalent to `weights: [500, 600]`. Remote providers expect numeric weights. #### `styles` Default: `['normal', 'italic']` Defines the styles that should be downloaded for a font. #### `subsets` Default: `['cyrillic-ext', 'cyrillic', 'greek-ext', 'greek', 'vietnamese', 'latin-ext', 'latin']` Defines the subsets that should be downloaded for a font. Characters outside the downloaded subsets render in a fallback font. If your content uses another script, such as Arabic, Hebrew, or Devanagari, add its subset here or for a single font in [`families`](#families): ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ { name: 'Cairo', subsets: ['arabic', 'latin', 'latin-ext'] }, ], } }) ``` #### `glyphs` Default: *None* Reduces every font file that is emitted to the glyphs needed to render these characters. Accepts a string of text, an array of characters, or [`unicode-range`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range) values, and can be overridden for a single font with [`families`](#families). ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { defaults: { glyphs: 'Handgloves & 0123', }, } }) ``` Unicode ranges use the same syntax as the `unicode-range` descriptor, and can be mixed with characters: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { defaults: { glyphs: ['U+0020-007E', 'U+2018-201D', 'U+2026'], }, } }) ``` A range is expanded to the characters it covers, so keep them tight. Ranges covering more than 65,536 codepoints in total are ignored with a warning. Where a provider can subset server-side, such as Google Fonts, the characters are passed through to it so the full file is never downloaded. Every other font file is subsetted after download, which needs the [`subset-font`](https://github.com/papandreou/subset-font) package. We will offer to install it the first time you run Nuxt with `glyphs` set, or you can add it yourself: ```bash [Terminal] npm install --save-dev subset-font ``` It is not a dependency of Nuxt Fonts, as the harfbuzz WebAssembly it loads is several megabytes and only projects that subset a font need it. Where we cannot ask, such as in CI, we warn instead, and the build fails before downloading any font that needs subsetting locally. ::warning Subsetting modifies the font files you ship. Check that the licence of each font allows it. :: #### `variableAxis` Default: *None* Chooses the values a variable font is shipped at, for every family. Each OpenType axis tag takes an array of values: a number or string, such as `CASL: [1]`, pins the axis to a single value, and a `[min, max]` pair or `{ min, max }` object, such as `MONO: [{ min: 0, max: 1 }]`, narrows it to an inclusive range. This can be overridden for a single font with [`families`](#families). ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { defaults: { variableAxis: { CASL: [1], MONO: [{ min: 0, max: 1 }], }, }, } }) ``` Providers that can instance a font server-side, such as Google Fonts, serve the file already resolved at those values. Otherwise the axis is applied to the downloaded file with [`subset-font`](https://github.com/papandreou/subset-font), which needs a glyph list to subset to: either the family's `glyphs`, or the characters the face's `unicode-range` declares. Without either, the file is emitted untouched and a `font-variation-settings` descriptor renders the font at the requested values instead. `wght` and `ital` are left alone, because `@font-face` descriptors already express them. ::warning Applying an axis is a subsetting pass, so it modifies the font files you ship. Check that the licence of each font allows it. :: ::note This option is experimental. Provider support and the option shape may change. :: #### `fallbacks` Default: ```ts { 'serif': ['Times New Roman', 'Georgia', 'Noto Serif'], 'sans-serif': ['Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'], 'monospace': ['Courier New', 'Roboto Mono', 'Noto Sans Mono'], 'cursive': ['Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'], 'fantasy': ['Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'], 'system-ui': ['Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'], 'ui-serif': ['Times New Roman', 'Georgia', 'Noto Serif'], 'ui-sans-serif': ['Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'], 'ui-monospace': ['Courier New', 'Roboto Mono', 'Noto Sans Mono'], 'ui-rounded': [], 'emoji': [], 'math': [], 'fangsong': [], } ``` If you use a generic font family like `Roboto, sans-serif`, we will 'translate' that generic family name into one or more font families when generating fallback metrics. You can customize which families we use. (One or two works best.) #### `preload` Default: *automatic* Controls which `@font-face` declarations get a `` in the initially rendered HTML. Preload hints are only rendered in production builds. By default we preload the highest priority font face for a family, as long as it has a remote or local URL and does not define a `unicode-range` (in other words, subsetted fonts like those from Google Fonts are not preloaded). Set `preload: true` to preload a single font face for every family. It picks a face from the first configured [`subsets`](#subsets) entry (otherwise one covering Basic Latin), prefers upright over italic, and then prefers the weight closest to 400. Pass an object with any of `subsets`, `styles` and `weights` to preload every font face that matches all of the given values. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { defaults: { // preload only the matching font faces preload: { subsets: ['latin'], styles: ['normal'], weights: [400] }, // or preload one upright font face near weight 400 in the first configured subset (or Basic Latin) // preload: true, // or opt out entirely // preload: false, // or decide for each font face // preload: (family, font) => font.weight === 400, }, } }) ``` A family reduced to a set of [`glyphs`](#glyphs) is not split into named subsets, so it is not excluded by a `subsets` filter. ### `families` This is an array which defines the font options for specific fonts. You can use any properties from [defaults](#defaults), while there are some additional properties: Example of `families`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ // do not resolve this font with any provider from `@nuxt/fonts` { name: 'Custom Font', provider: 'none' }, // only resolve this font with the `google` provider { name: 'My Font Family', provider: 'google' }, // specify specific font data - this will bypass any providers { name: 'Other Font', src: 'https://example.com/font.woff2', weight: 'bold' }, // entries sharing a name are combined, so each `src` becomes its own font face { name: 'Brand Font', src: '/brand-regular.woff2', weight: 400 }, { name: 'Brand Font', src: '/brand-black.woff2', weight: 900 }, ] } }) ``` #### `name` Default: *None* Defines the name of the font that should be given the option. This is required for every item in the `families` array. #### `global` Default: `false` Defines whether to inject `@font-face` regardless of usage in project. This is the escape hatch for fonts Nuxt Fonts can't detect by scanning your CSS: see [when a font isn't picked up](https://nuxt.com/modules/fonts/usage#when-a-font-isnt-picked-up). The `@font-face` rule and any preload hints come from a single stylesheet loaded on every page. Font fallback metrics work by rewriting the `font-family` declaration that uses the family, so they're generated wherever Nuxt Fonts can see the family being used in your CSS, and not for the usage it can't see. #### `provider` Default: *None* Defines the provider that is used for the given font. You can choose any providers from `none`, `google`, `googleicons`, `bunny`, `fontshare`, `fontsource`, `adobe`, `npm`, `local`. #### `src` Default: *None* Defines the src that should be used for the given font. If this is defined, then no other providers will be used for the given font family. #### `preload` Default: *inherited from [`defaults.preload`](#preload)* Overrides the preload behaviour for this font family. The option is used wherever the family is preloaded, which is every route it is used on unless a route rule names the family, in which case it is preloaded on the routes that match the rule, with the option the rule gives for it, and on no others. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ { name: 'Roboto', preload: { subsets: ['latin'] } }, ] } }) ``` A family named in a route rule is preloaded on the routes that match it, and on no others. The rule uses the same patterns as any other route rule, so `/inbox/**` matches the inbox route and everything below it. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], routeRules: { '/inbox/**': { fonts: { preload: { 'JetBrains Mono': { subsets: ['latin'] } } } }, } }) ``` Each family is preloaded with the option given for it, which takes the same shape as the [`preload`](#preload) option of a family. A family named in more than one rule is preloaded with the faces the first of them asks for. The option of a family belongs either here or in the [`preload`](#preload) option of the family, not in both. A family named in a rule is not preloaded on any other route, so an option set for it in `fonts.families` has no effect. The font files of a family restricted to route rules are preloaded by the server, as their URLs are only known once the fonts have been resolved. The preload is therefore only rendered in the HTML of the routes that match. #### `display` Default: *None* (`swap` when the resolved font data does not specify one) Defines the `font-display` descriptor of every `@font-face` generated for the given font family, overriding any value the provider returns. #### `unicodeRange` Default: *None* Defines the `unicode-range` descriptor of every `@font-face` generated for the given font family, overriding any value the provider returns. This can be used to load a font for a limited set of characters only. A family with a `unicode-range` counts as subsetted, so it is not preloaded unless you set [`preload`](#preload) for it explicitly. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ { name: 'Rowdies', provider: 'google', display: 'optional', unicodeRange: ['U+0040'] }, ] } }) ``` #### `ascentOverride`, `descentOverride`, `lineGapOverride` and `sizeAdjust` Default: *None* Defines the [font metric override descriptors](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override) of every `@font-face` generated for the given font family. These apply to the family itself; the metrics of the fallback fonts we generate for it are calculated for you. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ { name: 'My Font', src: '/my-font.woff2', descentOverride: '20%' }, ] } }) ``` #### `glyphs` Default: *inherited from [`defaults.glyphs`](#defaults)* Reduces every font file emitted for this family to the glyphs needed to render these characters, whichever provider served it. A `unicode-range` covering those characters is generated for you. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ { name: 'Rowdies', provider: 'google', glyphs: 'Nuxt Fonts' }, { name: 'Satoshi', glyphs: ['U+0020-007E', 'U+2018-201D', 'U+2026'] }, ] } }) ``` #### `variableAxis` Default: *inherited from [`defaults.variableAxis`](#defaults)* Chooses the values this family's variable font is shipped at, with an array of values for each OpenType axis tag. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { families: [ { name: 'Recursive', variableAxis: { CASL: [1], MONO: [{ min: 0, max: 1 }] } }, ] } }) ``` ## Provider Options Providers can have their own options. These options are passed directly to different font providers. Please refer to the [provider documentation](https://nuxt.com/modules/fonts/providers) for more information. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { google: {}, local: {}, npm: {}, adobe: { id: ['fontkitId1', 'fontkitId2'], } } }) ``` ## `providers` This defines the behavior of the providers used. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { providers: { // You can pass a new custom provider - see more in the providers documentation // for what this file should look like custom: '~/providers/custom', // Or you can disable a built-in provider google: false, } } }) ``` ## `assets` This defines the behavior of the assets used. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { assets: { // The directory font files are served from. prefix: 'fonts' } } }) ``` In a Vite production build, `prefix` names a directory inside `app.buildAssetsDir`, so the default resolves to `/_nuxt/fonts`. In development, and with the webpack and rspack builders, it is a public path and defaults to `/_fonts`. See [where fonts are served from](https://nuxt.com/modules/fonts/advanced#where-fonts-are-served-from). ## `cache` Font metadata and downloaded font files are cached between builds in `node_modules/.cache/nuxt/fonts/meta`. You can change where that happens, provide your own [unstorage](https://unstorage.unjs.io/) instance, or turn persistent caching off (in which case an in-memory cache is used). ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { // a directory, resolved relative to your project root cache: '.cache/fonts', // or your own storage // cache: createStorage({ driver: redisDriver({ base: 'fonts' }) }), // or no persistent cache at all // cache: false, } }) ``` ## `priority` You can customize the order in which providers are checked. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { priority: ['bunny', 'google'], } }) ``` ## `provider` In some cases you may wish to use only one font provider. This is equivalent to disabling all other font providers, so a per-family `provider` other than the one configured here will not be used. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { provider: 'google' } }) ``` ## `devtools` Default: `true` Adds a **Fonts** panel to [Nuxt DevTools](https://nuxt.com/modules/devtools), listing every family resolved for your app: the provider that served it, the faces generated for it, where each is used, and any warnings raised while resolving it. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { // Disable the Nuxt DevTools integration devtools: false } }) ``` ## `processCSSVariables` You can enable support for processing CSS variables for font family names. Available options: `true`, `false`, `font-prefixed-only`, or a custom prefix. Default is `font-prefixed-only`. Note that `true` might cause some performance impacts. Passing a custom string processes only the CSS variables matching that prefix, so `'my-app'` will process `--my-app-*` variables and nothing else. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { // You can enable support for processing CSS variables for font family names. processCSSVariables: true } }) ``` ::tip If you previously set `processCSSVariables` to `true` for Tailwind v4 support, it is no longer needed or recommended in v0.11.0 and later. :: ## `throwOnError` Defines what happens when no provider can resolve a font, or a font file cannot be downloaded. It defaults to `false` while developing (so a flaky provider does not block you) and `true` when building (so you don't ship a build with missing fonts). A provider that fails does not fail the build on its own: resolution carries on to the next provider, and an error is only raised once none of them can serve the family. Font metadata requests and font file downloads are both retried a few times with backoff before that applies, so it only takes effect for persistent failures. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { // continue the build with a warning instead of failing throwOnError: false } }) ``` ::tip If your builds fail intermittently with a `404` from `fonts.gstatic.com`, consider [caching font downloads between builds](https://nuxt.com/modules/fonts/advanced#caching-fonts-between-builds) or switching to a provider with stable URLs, such as `bunny`. :: ## `experimental` Defines whether to enable experimental features. All of them are `false` by default. ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/fonts'], fonts: { experimental: { // Stops adding `local()` sources to generated `@font-face` rules. Default is `false`. disableLocalFallbacks: true } } }) ``` ## Sitemap See the full [sitemap](https://nuxt.com/sitemap.md) for all pages.