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.

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.

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

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

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: {},
    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/'
    }
  }
})

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.

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 or font-prefixed-only. Default is font-prefixed-only. Note that true might cause some performance impacts.

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

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