Font Optimization
Nuxt has a core module (@nuxt/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@importrules 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-familydeclaration in your CSS. Nuxt Fonts finds the font and generates the@font-facerules for you.
Installation
Add the Nuxt Fonts module to your project:
npx nuxt add fontsThis 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:
<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 of your nuxt.config:
body {
font-family: 'Inter', sans-serif;
}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.
<style> blocks. A font-family in an inline style attribute isn't detected. See fonts that aren't detected.Web Fonts
Nuxt Fonts resolves fonts from several web font providers, such as Google Fonts, Bunny Fonts, Fontshare, and Fontsource. 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 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:
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 for all options.
Local Fonts
To use your own font files, store them in the 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:
-| public/
---| fonts/
-----| my-font.woff2 # 400, normal
-----| my-font-bold.woff2 # 700, normal
-----| my-font-700-italic.woff2 # 700, italicThen use the font by its name:
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, 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:
export default defineNuxtConfig({
modules: ['@nuxt/fonts'],
fonts: {
families: [
{ name: 'My Variable Font', weights: ['100 900'] },
],
},
})Then use the font by its name:
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:
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:
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:
@import "tailwindcss";
@theme {
--font-display: 'Inter', sans-serif;
}Then apply the font with the font-display utility class. See the Nuxt Fonts usage guide for more details, and for UnoCSS.
Next Steps
See the Nuxt Fonts documentation for all its features:
- Configuration: set the weights, styles, subsets, and preloading of your fonts.
- Providers: configure the built-in providers, such as Adobe Fonts, or write your own.
- How it works: learn how Nuxt Fonts resolves fonts and generates fallback metrics.