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],
      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 set glyphs need it.

fallbacks

Default:

{
  'serif': ['Times New Roman'],
  'sans-serif': ['Arial'],
  'monospace': ['Courier New'],
  'cursive': [],
  'fantasy': [],
  'system-ui': [
    'BlinkMacSystemFont',
    'Segoe UI',
    'Roboto',
    'Helvetica Neue',
    'Arial',
  ],
  'ui-serif': ['Times New Roman'],
  'ui-sans-serif': ['Arial'],
  'ui-monospace': ['Courier New'],
  '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.

provider

Default: None

Defines the provider that is used for the given font. You can choose any providers from none, google, 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' },
    ]
  }
})

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 baseURL where font files are served.
      prefix: '/_fonts/'
    }
  }
})

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: {
      // Defines whether to enable adding local fallbacks. Default is `false`.
      disableLocalFallbacks: true
    }
  }
})