🔠 CSS font-display — Complete Tutorial

The font-display descriptor controls **how web fonts load and render** on your website. It defines what the browser should do **while the custom font is loading**, and how it should behave if the font takes too long to load or fails entirely.

>>“font-display lets you balance performance and design — swap instantly, wait for font, or fall back gracefully.”

Note

✔ Only works inside @font-face
✔ Crucial for performance and avoiding invisible text (FOIT)
✔ Affects how quickly text appears to users

📦 Syntax

@font-face with font-display

@font-face {
  font-family: "MyFont";
  src: url("myfont.woff2") format("woff2");
  font-display: swap;
}
ValueBehavior
autoBrowser decides
blockText invisible briefly, then custom font appears
swapText shows immediately using fallback, then swaps to custom
fallbackShows fallback instantly, swaps only if font loads quickly
optionalFallback shown; custom font used only if cache/quick

🎨 Understanding font-display Modes

1️⃣ font-display: auto

Default behavior. Browser chooses strategy depending on connection, font size, etc.

2️⃣ font-display: block (FOIT — Invisible Text)

block

@font-face {
  font-family: "MyFont";
  src: url("font.woff2");
  font-display: block;
}

The browser hides text until the font loads (up to 3 seconds). After that, text appears in custom font or fallback if failed.

Note

❌ Causes FOIT → Flash of Invisible Text

3️⃣ font-display: swap (Recommended)

swap

@font-face {
  font-family: "MyFont";
  src: url("font.woff2");
  font-display: swap;
}

Text appears immediately using fallback font → once custom font loads, the text “swaps” to the custom font.

Note

✔ Best for performance + usability

4️⃣ font-display: fallback

fallback

@font-face {
  font-family: "MyFont";
  src: url("font.woff2");
  font-display: fallback;
}

Text uses fallback font first. Custom font replaces it only if loaded within ~100ms.

5️⃣ font-display: optional (Best for very fast sites)

optional

@font-face {
  font-family: "MyFont";
  src: url("font.woff2");
  font-display: optional;
}

If the font loads instantly (from cache), it appears. Otherwise, the browser **sticks to the fallback font permanently**.

Note

✔ Best for users on slow networks ✔ Used by Google Fonts for speed

🎯 Visual Comparison

ModeInitial TextAfter Font Loads
block❌ Invisible✔ Custom
swap✔ Fallback visible✔ Switches to custom
fallback✔ Fallback visible⚠️ Swaps only if fast
optional✔ Fallback visible⚠️ Usually remains fallback

🧪 Real-World Use Cases

1️⃣ Best for UI Websites → swap

UI font loading

@font-face {
  font-family: "Inter";
  src: url("Inter.woff2");
  font-display: swap;  /* best UI experience */
}

2️⃣ Article / Blog Typography → fallback

blog

@font-face {
  font-family: "Merriweather";
  src: url("Merriweather.woff2");
  font-display: fallback;
}

3️⃣ Performance-First Apps → optional

performance

@font-face {
  font-family: "Poppins";
  src: url("poppins.woff2");
  font-display: optional;
}

Prevents layout shift on slow networks.

⚠️ Common Mistakes

  • ❌ Using block on text-heavy websites (causes invisible text)
  • ❌ Assuming font-display works outside @font-face
  • ❌ Not providing fallback fonts (system-ui, serif, sans-serif)
  • ❌ Using large unoptimized fonts (slows down swap)

Note

Always include a performance-friendly fallback font stack.

🔥 Summary

font-display determines how your text behaves while custom fonts load. Choosing the right mode is crucial for UX, speed, and visual stability.

  • swap → Best balance (recommended)
  • fallback → Good for reading content
  • optional → Top performance option
  • block → Avoid unless necessary
>>“Fast text beats fancy text — font-display ensures both can coexist.”