---
title: "Font Optimization"
description: "Learn how to optimize web fonts in your Nuxt application with Nuxt Fonts."
canonical_url: "https://nuxt.com/docs/4.x/getting-started/fonts"
---
# Font Optimization

> Learn how to optimize web fonts in your Nuxt application with Nuxt Fonts.

Nuxt has a core module ([`@nuxt/fonts`](https://nuxt.com/modules/fonts)) to optimize your web fonts and remove external network requests for improved privacy and performance:

- **Self-hosting:** Nuxt Fonts downloads fonts at build time and serves them from your own domain with long-lived cache headers. The browser sends no requests to Google or other font providers for these fonts. Remove any `<link>` tags or `@import` rules that load fonts from a provider, because Nuxt Fonts doesn't process them.
- **Less layout shift:** Nuxt Fonts adjusts a local system font to match the metrics of each web font. Text barely moves when the web font loads.
- **No code to write:** Name a font in a `font-family` declaration in your CSS. Nuxt Fonts finds the font and generates the `@font-face` rules for you.

## Installation

Add the Nuxt Fonts module to your project:

```bash [Terminal]
npx nuxt add fonts
```

This command installs `@nuxt/fonts` and adds it to the `modules` of your `nuxt.config`.

## Usage

To use a font, add a `font-family` declaration to your CSS:

```vue [app/app.vue]
<template>
  <h1>Hello Nuxt Fonts!</h1>
</template>

<style scoped>
h1 {
  font-family: 'Roboto', sans-serif;
}
</style>
```

Nuxt Fonts detects `Roboto` and resolves it from a font provider. It then injects the `@font-face` rules into the same stylesheet.

Fonts load where your CSS uses them. To apply a font to your entire application, declare it in a global stylesheet and add the stylesheet to the [`css` property](https://nuxt.com/docs/4.x/getting-started/styling#the-css-property) of your `nuxt.config`:

::code-group
```css [app/assets/css/main.css]
body {
  font-family: 'Inter', sans-serif;
}
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  css: ['~/assets/css/main.css'],
})
```
::

Nuxt Fonts only resolves the first font in a `font-family` list. It uses the other fonts in the list, such as `sans-serif`, to generate the fallback metrics.

::warning
Nuxt Fonts only processes CSS stylesheets and `<style>` blocks. A `font-family` in an inline `style` attribute isn't detected. See [fonts that aren't detected](#fonts-that-arent-detected).
::

## Web Fonts

Nuxt Fonts resolves fonts from several web font providers, such as [Google Fonts](https://fonts.google.com), [Bunny Fonts](https://fonts.bunny.net), [Fontshare](https://www.fontshare.com), and [Fontsource](https://fontsource.org). You don't need to configure them: the first provider that has the font serves it.

By default, Nuxt Fonts loads the `400 700` weight range in `normal` and `italic` styles. Google Fonts and Fontsource serve a [variable font](https://fonts.google.com/knowledge/introducing_type/introducing_variable_fonts) when the family has one. A variable font covers a range of weights with one file, instead of one file for each weight.

To load other weights, or to choose a provider for a font, configure the font in the `fonts.families` option of your `nuxt.config`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      // Load every weight of the variable Inter font
      { name: 'Inter', weights: ['100 900'] },
      // Only load these weights of Roboto, from Google Fonts
      { name: 'Roboto', weights: [400, 700], provider: 'google' },
    ],
  },
})
```

To use the same options for all fonts, set them in `fonts.defaults` instead. You can also change the subsets that Nuxt Fonts loads, for example to support Cyrillic or Arabic text. See the [font options](https://nuxt.com/modules/fonts/configuration#font-options) for all options.

## Local Fonts

To use your own font files, store them in the [`public/`](https://nuxt.com/docs/4.x/directory-structure/public) directory. Nuxt Fonts scans it for `woff2`, `woff`, `ttf`, `otf`, and `eot` files that match the `font-family` names in your CSS.

The filename tells Nuxt Fonts the weight and style of each file. A file without a weight or style is the `400` weight in the `normal` style:

```bash [Directory structure]
-| public/
---| fonts/
-----| my-font.woff2              # 400, normal
-----| my-font-bold.woff2         # 700, normal
-----| my-font-700-italic.woff2   # 700, italic
```

Then use the font by its name:

```css [app/assets/css/main.css]
body {
  font-family: 'My Font', sans-serif;
}
```

Nuxt Fonts converts `My Font` to `my-font` to look up the files.

For a variable font, put its weight range in the filename, such as `public/fonts/my-variable-font-100-900.woff2`. A filename marked `variable` or `VF` without a range covers `100 900`. Nuxt Fonts only declares the [default weights](#web-fonts), `400 700`, even for a variable font file, so other weights render at the nearest one in that range. To use its full range, configure the weights of the font:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'My Variable Font', weights: ['100 900'] },
    ],
  },
})
```

Then use the font by its name:

```css [app/assets/css/main.css]
h1 {
  font-family: 'My Variable Font', sans-serif;
  font-weight: 900;
}
```

To use a font file with a different name, or a file hosted elsewhere, set its `src` in `fonts.families`. You can repeat a font name to add a file for each weight:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'Brand Font', src: '/brand-regular.woff2', weight: 400 },
      { name: 'Brand Font', src: '/brand-black.woff2', weight: 900 },
    ],
  },
})
```

## Fonts That Aren't Detected

Nuxt Fonts only resolves the fonts that it finds in your CSS. It doesn't detect fonts in inline styles, in inline SVG, in third-party stylesheets, or fonts that you only apply at runtime.

For these fonts, set `global: true` in `fonts.families`. Nuxt Fonts then adds the `@font-face` rules of the font to every page:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'Anton', global: true },
    ],
  },
})
```

Every visitor downloads the CSS for each global font, so only use this option when you need it.

This option doesn't apply to SVG files that you load with an `<img>` tag, because they can't use the fonts of the page. Embed the font in these SVG files instead.

## Tailwind CSS

Nuxt Fonts reads the CSS that Tailwind CSS generates, so you can declare your fonts as theme variables:

```css [app/assets/css/main.css]
@import "tailwindcss";

@theme {
  --font-display: 'Inter', sans-serif;
}
```

Then apply the font with the `font-display` utility class. See the [Nuxt Fonts usage guide](https://nuxt.com/modules/fonts/usage#tailwind-css) for more details, and for UnoCSS.

## Next Steps

See the Nuxt Fonts documentation for all its features:

- [Configuration](https://nuxt.com/modules/fonts/configuration): set the weights, styles, subsets, and preloading of your fonts.
- [Providers](https://nuxt.com/modules/fonts/providers): configure the built-in providers, such as Adobe Fonts, or write your own.
- [How it works](https://nuxt.com/modules/fonts/advanced#how-it-works): learn how Nuxt Fonts resolves fonts and generates fallback metrics.


## Sitemap

See the full [sitemap](https://nuxt.com/sitemap.md) for all pages.