> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cloudflare/vinext/llms.txt
> Use this file to discover all available pages before exploring further.
# next/font
> Automatic font optimization for Google Fonts and local fonts
The `next/font` module provides automatic font optimization with zero layout shift, reduced network requests, and built-in subsetting.
## Google Fonts
Import fonts from Google Fonts CDN (dev) or self-host them (production).
### Import
```typescript theme={null}
import { Inter, Roboto_Mono } from 'next/font/google'
```
### Basic Usage
```tsx theme={null}
import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'] })
export default function Layout({ children }) {
return (
{children}
)
}
```
### API Reference
Font subsets to load (reduces file size).
Common subsets:
* `'latin'` — Latin alphabet (English, French, German, etc.)
* `'latin-ext'` — Extended Latin (Eastern European)
* `'cyrillic'` — Cyrillic alphabet (Russian, Ukrainian, etc.)
* `'greek'` — Greek alphabet
* `'vietnamese'` — Vietnamese
```tsx theme={null}
const inter = Inter({
subsets: ['latin', 'latin-ext']
})
```
Font weights to load.
```tsx theme={null}
// Single weight
const inter = Inter({ subsets: ['latin'], weight: '400' })
// Multiple weights
const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
// Variable font (all weights)
const inter = Inter({ subsets: ['latin'] }) // Loads 100-900
```
Font styles to load.
```tsx theme={null}
const inter = Inter({ subsets: ['latin'], style: ['normal', 'italic'] })
```
CSS `font-display` value.
* `'swap'` — Show fallback immediately, swap when loaded (recommended)
* `'optional'` — Use font if cached, otherwise use fallback
* `'fallback'` — Brief block period, then swap
* `'block'` — Block rendering until font loads (avoid)
```tsx theme={null}
const inter = Inter({ subsets: ['latin'], display: 'optional' })
```
Add `` for faster loading.
```tsx theme={null}
const inter = Inter({ subsets: ['latin'], preload: true })
```
Fallback fonts when the web font is loading or unavailable.
```tsx theme={null}
const inter = Inter({
subsets: ['latin'],
fallback: ['system-ui', 'arial', 'sans-serif']
})
```
Automatically adjust fallback fonts to reduce layout shift.
```tsx theme={null}
const inter = Inter({ subsets: ['latin'], adjustFontFallback: false })
```
CSS variable name for the font.
```tsx theme={null}
const inter = Inter({
subsets: ['latin'],
variable: '--font-inter'
})
// Usage in CSS:
// font-family: var(--font-inter);
```
### Return Value
CSS class name that applies the font.
```tsx theme={null}
const inter = Inter({ subsets: ['latin'] })
This text uses Inter
```
Inline style object with `fontFamily`.
```tsx theme={null}
This text uses Inter
```
CSS class name that sets the CSS variable.
```tsx theme={null}
const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
{/* Now var(--font-inter) is available everywhere */}
```
### Examples
#### Multiple Fonts
```tsx theme={null}
import { Inter, Roboto_Mono } from 'next/font/google'
const inter = Inter({ subsets: ['latin'] })
const robotoMono = Roboto_Mono({ subsets: ['latin'] })
export default function Layout({ children }) {
return (
{children}
)
}
```
#### With Tailwind CSS
```tsx theme={null}
// app/layout.tsx
import { Inter } from 'next/font/google'
const inter = Inter({
subsets: ['latin'],
variable: '--font-inter'
})
export default function RootLayout({ children }) {
return (
{children}
)
}
```
```javascript theme={null}
// tailwind.config.js
module.exports = {
theme: {
extend: {
fontFamily: {
sans: ['var(--font-inter)', 'sans-serif'],
},
},
},
}
```
#### Single Page
```tsx theme={null}
import { Playfair_Display } from 'next/font/google'
const playfair = Playfair_Display({ subsets: ['latin'] })
export default function ArticlePage() {
return (
Beautiful Typography
Using Playfair Display
)
}
```
## Local Fonts
Use fonts from local files.
### Import
```typescript theme={null}
import localFont from 'next/font/local'
```
### Basic Usage
```tsx theme={null}
import localFont from 'next/font/local'
const myFont = localFont({
src: './fonts/my-font.woff2'
})
export default function Layout({ children }) {
return (
{children}
)
}
```
### API Reference
Font file path(s).
**Single file:**
```tsx theme={null}
const myFont = localFont({
src: './fonts/my-font.woff2'
})
```
**Multiple weights:**
```tsx theme={null}
const myFont = localFont({
src: [
{
path: './fonts/my-font-regular.woff2',
weight: '400',
style: 'normal',
},
{
path: './fonts/my-font-bold.woff2',
weight: '700',
style: 'normal',
},
]
})
```
Default font weight (when using single `src` string).
```tsx theme={null}
const myFont = localFont({
src: './fonts/my-font.woff2',
weight: '600'
})
```
Default font style.
```tsx theme={null}
const myFont = localFont({
src: './fonts/my-font-italic.woff2',
style: 'italic'
})
```
CSS `font-display` value (same as Google Fonts).
Fallback fonts.
```tsx theme={null}
const myFont = localFont({
src: './fonts/my-font.woff2',
fallback: ['system-ui', 'sans-serif']
})
```
CSS variable name.
```tsx theme={null}
const myFont = localFont({
src: './fonts/my-font.woff2',
variable: '--font-custom'
})
```
Add preload hint.
Custom CSS properties for the `@font-face` rule.
```tsx theme={null}
const myFont = localFont({
src: './fonts/my-font.woff2',
declarations: [
{ prop: 'font-feature-settings', value: '"liga" 1' },
{ prop: 'font-variation-settings', value: '"wght" 400' }
]
})
```
### Examples
#### Variable Font
```tsx theme={null}
import localFont from 'next/font/local'
const myFont = localFont({
src: './fonts/my-variable-font.woff2',
variable: '--font-custom'
})
export default function Layout({ children }) {
return (
{children}
)
}
```
#### Multiple Weights and Styles
```tsx theme={null}
import localFont from 'next/font/local'
const myFont = localFont({
src: [
{
path: './fonts/my-font-light.woff2',
weight: '300',
style: 'normal',
},
{
path: './fonts/my-font-regular.woff2',
weight: '400',
style: 'normal',
},
{
path: './fonts/my-font-regular-italic.woff2',
weight: '400',
style: 'italic',
},
{
path: './fonts/my-font-bold.woff2',
weight: '700',
style: 'normal',
},
]
})
export default function Layout({ children }) {
return (
{children}
)
}
```
## Self-Hosting Google Fonts
In production builds, vinext automatically downloads and self-hosts Google Fonts:
1. **Build time**: Plugin fetches font CSS and `.woff2` files from Google
2. **Assets**: Fonts are bundled with your app
3. **Runtime**: No requests to Google Fonts CDN
**Benefits:**
* Faster loading (no DNS lookup, no third-party request)
* Better privacy (no data sent to Google)
* Works offline
**Dev mode**: Fonts load from Google CDN (faster iteration).
## Performance
### Zero Layout Shift
vine automatically generates fallback font metrics to prevent layout shift:
```css theme={null}
/* Generated by vinext */
@font-face {
font-family: '__Inter_Fallback';
src: local('Arial');
ascent-override: 90.2%;
descent-override: 22.4%;
line-gap-override: 0%;
size-adjust: 107.4%;
}
```
### Subsetting
Loading only the characters you need:
```tsx theme={null}
const inter = Inter({
subsets: ['latin'], // Only Latin characters
})
// File size: ~30KB instead of ~120KB (all subsets)
```
### Preloading
Preload hints ensure fonts load early:
```html theme={null}
```
## CSS Variables
Use CSS variables for flexible theming:
```tsx theme={null}
// app/layout.tsx
import { Inter, Roboto_Mono } from 'next/font/google'
const inter = Inter({ subsets: ['latin'], variable: '--font-sans' })
const robotoMono = Roboto_Mono({ subsets: ['latin'], variable: '--font-mono' })
export default function RootLayout({ children }) {
return (
{children}
)
}
```
```css theme={null}
/* globals.css */
body {
font-family: var(--font-sans), sans-serif;
}
code {
font-family: var(--font-mono), monospace;
}
```
## Common Fonts
vinext provides named exports for popular Google Fonts:
```typescript theme={null}
import {
Inter,
Roboto,
Roboto_Mono,
Open_Sans,
Lato,
Poppins,
Montserrat,
Source_Code_Pro,
Noto_Sans,
Raleway,
Ubuntu,
Nunito,
Playfair_Display,
Merriweather,
PT_Sans,
Fira_Code,
JetBrains_Mono,
Geist,
Geist_Mono,
} from 'next/font/google'
```
For other fonts, use the dynamic accessor:
```typescript theme={null}
import googleFonts from 'next/font/google'
const dmSans = googleFonts.DM_Sans({ subsets: ['latin'] })
```
## Limitations
**Module-level only**: Font loaders must be called at module level (not inside components).
```tsx theme={null}
// ✅ Correct
const inter = Inter({ subsets: ['latin'] })
export default function Page() {
return
Text
}
// ❌ Wrong
export default function Page() {
const inter = Inter({ subsets: ['latin'] })
return
Text
}
```
**Local font paths**: Must be relative to the file where `localFont` is called.
**Build-time download**: Google Fonts are fetched at build time. Network issues during build will cause failures.
## Source
[View Google Fonts source →](https://github.com/stackblitz/vinext/blob/main/packages/vinext/src/shims/font-google.ts)
[View local fonts source →](https://github.com/stackblitz/vinext/blob/main/packages/vinext/src/shims/font-local.ts)
Implementation:
* `/home/daytona/workspace/source/packages/vinext/src/shims/font-google.ts`
* `/home/daytona/workspace/source/packages/vinext/src/shims/font-local.ts`