Configuration

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:

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 or a separate behaviour for a specific font with families.

defaults

This defines the default font options for all fonts.

Example of defaults:

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.

The local provider 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.

glyphs

Default: None

Reduces every font file that is emitted to the glyphs needed to render these characters. Accepts a string of text or an array of characters, and can be overridden for a single font with families.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    defaults: {
      glyphs: 'Handgloves & 0123',
    },
  }
})

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 package. We will offer to install it the first time you run Nuxt with glyphs set, or you can add it yourself:

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.

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.

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, 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.

fallbacks

Default:

{
  'serif': ['Times New Roman', 'Georgia', 'Noto Serif'],
  'sans-serif': ['BlinkMacSystemFont', 'Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'],
  'monospace': ['Courier New', 'Roboto Mono', 'Noto Sans Mono'],
  'cursive': ['BlinkMacSystemFont', 'Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'],
  'fantasy': ['BlinkMacSystemFont', 'Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'],
  'system-ui': ['BlinkMacSystemFont', 'Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'],
  'ui-serif': ['Times New Roman', 'Georgia', 'Noto Serif'],
  'ui-sans-serif': ['BlinkMacSystemFont', '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 <link rel="preload"> in the initially rendered HTML.

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).

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    defaults: {
      // preload only the font faces covering these subsets
      preload: { subsets: ['latin'] },
      // or preload the highest priority font face for every family
      // preload: true,
      // or opt out entirely
      // preload: false,
      // or decide for each font face
      // preload: (family, font) => font.weight === 400,
    },
  }
})

families

This is an array which defines the font options for specific fonts. You can use any properties from defaults, while there are some additional properties:

Example of families:

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' },
    ]
  }
})

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.

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

Overrides the preload behaviour for this font family.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'Roboto', preload: { subsets: ['latin'] } },
    ]
  }
})

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 for it explicitly.

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 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.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'My Font', src: '/my-font.woff2', descentOverride: '20%' },
    ]
  }
})

glyphs

Default: inherited from defaults.glyphs

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.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'Rowdies', provider: 'google', glyphs: 'Nuxt Fonts' },
    ]
  }
})

variableAxis

Default: inherited from defaults.variableAxis

Chooses the values this family's variable font is shipped at, with an array of values for each OpenType axis tag.

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 for more information.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    google: {},
    local: {},
    npm: {},
    adobe: {
      id: ['fontkitId1', 'fontkitId2'],
    }
  }
})

providers

This defines the behavior of the providers used.

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.

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.

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 instance, or turn persistent caching off (in which case an in-memory cache is used).

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.

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.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    provider: 'google'
  }
})

devtools

Defines whether to enable devtools for Nuxt font, default is true

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.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    // You can enable support for processing CSS variables for font family names.
    processCSSVariables: true
  }
})

throwOnError

Defines what happens when a font cannot be resolved from a provider, 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).

Font metadata requests and font file downloads are both retried a few times with backoff before this applies, so it only takes effect for persistent failures.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    // continue the build with a warning instead of failing
    throwOnError: false
  }
})

experimental

Defines whether to enable experimental features. All of them are false by default.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    experimental: {
      // Stops adding `local()` sources to generated `@font-face` rules. Default is `false`.
      disableLocalFallbacks: true
    }
  }
})