Font Optimization

Analogy categoryAnalogies

The next/font module automatically self-hosts font files — including Google Fonts — by downloading them at build time and serving them from your own domain instead of fetching from an external network at runtime. This removes the extra DNS lookup and connection overhead of a third-party font request, and because Next.js knows the font's metrics ahead of time, it can inject fallback font CSS with matching size-adjust values, minimizing the layout shift that happens when a fallback font swaps to the real one.

🏏

Cricket analogy: Self-hosting fonts instead of fetching from an external CDN is like a stadium having its own on-site catering rather than waiting for delivery trucks to arrive mid-match — no external dependency delay during play.

Using next/font/google and next/font/local

For Google Fonts, import a function like Inter from next/font/google, call it with options such as subsets and weight, and apply the returned className (or variable for CSS custom properties) to your root layout or a specific element. For self-owned font files — say, a custom brand typeface — use next/font/local, pointing src at the woff2 files in your project; both approaches produce the same build-time self-hosting and automatic font-display handling, avoiding a flash of invisible or unstyled text.

🏏

Cricket analogy: Choosing between next/font/google and next/font/local is like a franchise choosing between drafting an established international star (Google Fonts) versus developing homegrown academy talent (a custom brand typeface) — both routes reach the same playing squad.

tsx

// app/layout.tsx
import { Inter } from 'next/font/google';
import localFont from 'next/font/local';

const inter = Inter({
  subsets: ['latin'],
  weight: ['400', '600', '700'],
  variable: '--font-inter',
});

const brandFont = localFont({
  src: '../public/fonts/BrandSans.woff2',
  variable: '--font-brand',
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={`${inter.variable} ${brandFont.variable}`}>
      <body className={inter.className}>{children}</body>
    </html>
  );
}

next/font automatically sets font-display: swap behavior and generates adjusted fallback font metrics (size-adjust, ascent-override) so that the fallback system font occupies almost exactly the same space as the final web font, minimizing the visual jump when the real font finishes loading.

Applying Fonts Across the App

The recommended pattern is to load fonts once at the root layout and expose them as CSS variables via the variable option, then reference var(--font-inter) in your Tailwind config or global CSS wherever you need that typeface — this avoids re-declaring or re-downloading the font in every nested component. Loading the same font multiple times in different files with next/font/google is safe (Next.js deduplicates identical font requests at build time), but centralizing font declarations in the layout keeps the design system's typography consistent and easy to audit.

🏏

Cricket analogy: Loading a font once at the root layout and referencing it everywhere is like a board setting one official ball supplier (SG or Kookaburra) for the entire tournament rather than letting each match organizer source their own.

next/font must be called with static, literal arguments at the module top level (e.g., Inter({ subsets: ['latin'] }) directly) — you cannot dynamically construct the font name or options from a runtime variable, since font loading and self-hosting happens at build time via a compiler plugin, not at request time.

next/font self-hosts fonts (including Google Fonts) at build time, removing external network requests at runtime.
Automatic fallback font metric adjustment minimizes layout shift between the fallback and final web font.
next/font/google loads fonts from Google's catalog; next/font/local loads your own font files.
The variable option exposes a font as a CSS custom property for reuse across Tailwind config or global CSS.
Loading the same font in multiple files is deduplicated by Next.js, but centralizing declarations in the root layout is best practice.
next/font requires static, literal call arguments — font configuration cannot be computed dynamically at runtime.
font-display: swap and size-adjust handling are applied automatically to avoid flash of invisible/unstyled text.