Getting Started

Usage

Use Nuxt Fonts with any CSS framework or library.

Pure CSS

You can use Nuxt Fonts with pure CSS by adding font-family declarations to your CSS:

assets/css/fonts.css
div {
  font-family: 'Inter', sans-serif;
}
Note that Nuxt Fonts will only generate CSS for the first font in a font-family declaration. Subsequent fonts in the list will be used to generate metrics for font fallbacks.
Inline styles with font-family within your <template> don't work; only CSS stylesheets are processed. See when a font isn't picked up.

When a font isn't picked up

Nuxt Fonts resolves fonts by scanning the CSS your project generates for font-family declarations. A font that's never named in that CSS is never resolved, so no @font-face rule is emitted and the browser falls back to a system font.

Common places a font stays invisible to the scan:

  • a style attribute in a template, or any other inline style
  • a font-family inside an SVG, whether served from public/ or imported as an asset
  • a Tailwind v4 --font-* theme variable declared with @theme inline that no utility uses, which Tailwind drops before Nuxt Fonts sees it
  • a font named only at runtime, such as a family a user chooses and you apply through a CSS variable
  • a font set by CSS-in-JS, a third-party stylesheet, or a framework preset that isn't part of your own CSS

For all of these, declare the family with global: true and Nuxt Fonts emits its @font-face rules whether or not it finds a use for them:

nuxt.config.ts
export default defineNuxtConfig({
  fonts: {
    families: [
      { name: 'Anton', provider: 'google', global: true },
    ],
  },
})

You can then use font-family: 'Anton' anywhere, including in places Nuxt Fonts never scans.

Global families are injected into a single stylesheet loaded on every page, so keep the list short: every visitor downloads the CSS for each one.

Tailwind CSS

With Tailwind CSS you specify fonts using a CSS variable:

main.css
@theme {
  --font-display: "Inter", "sans-serif";
}

Overriding Tailwind's default font family works too, including via @theme inline, which compiles --font-sans down to --default-font-family:

main.css
@theme {
  --default-font-family: "Inter", sans-serif;
}
Nuxt Fonts reads the CSS Tailwind generates, so a font is only picked up if it ends up there. A --font-* theme variable that is never used by a utility (and is declared with @theme inline) is removed by Tailwind before Nuxt Fonts sees it. Use the utility at least once, declare it with @theme static, or set the font in fonts.families with global: true.
If you previously set processCSSVariables to true for Tailwind v4 support, it is no longer needed or recommended for v0.11.0 and above.

UnoCSS

You can use Nuxt Fonts with UnoCSS by setting fontFamily in your configuration file:

uno.config.js
import { defineConfig } from 'unocss'

export default defineConfig({
  theme: {
    fontFamily: {
      inter: 'Inter',
    },
  },
})

If you're using the Wind4 (Tailwind4) preset, set font instead of fontFamily.

    font: {
      inter: 'Inter',
    },

Configuration

Nuxt Fonts works out of the box with zero config, but you can always add some configurations for finer-grained control.

Providers

Font providers are designed to be pluggable and extensible, so no matter your setup you should be able to use an existing provider or write your own.