Font Display Swap

A CSS font-display strategy that renders text immediately in a fallback font while the custom font loads, then swaps to the custom font once downloaded. Prevents Flash of Invisible Text (FOIT).

Category: Performance (also: Front End, Design)

Author: Atomic Glue Performance Team

## Definition

The font-display CSS property controls how a web font is rendered while it is loading. The swap value tells the browser to render text with a fallback font immediately (no invisible text period), then swap to the custom font once it finishes downloading. This eliminates FOIT (Flash of Invisible Text) at the cost of causing a FOUT (Flash of Unstyled Text). For best CLS, font-display: optional paired with size-adjust overrides is often preferred.

## Font Display Values

auto: browser default (usually FOIT for 3 seconds). block: FOIT for a short timeout (3 seconds), then swap. swap: immediate fallback text, swap when loaded. fallback: FOIT for a very short timeout (100 ms), then fallback text with no swap. optional: FOIT for a very short timeout, then fallback text; custom font is used only if cached. For performance, swap prevents invisible text but can cause layout shifts.

## Common Misunderstandings

font-display: swap alone does NOT fix CLS caused by fonts. When the font swaps from fallback to custom, the text may reflow if the custom font has different metrics. Use the size-adjust, ascent-override, descent-override, and line-gap-override descriptors to match the font metrics and eliminate reflow. Also, font-display must be declared inside @font-face, not in a CSS rule.

## Optimization Tips

Use font-display: optional for body text where visual stability matters more than brand font. Use font-display: swap for headings and display text where the brand font is important. Always pair with size-adjust overrides to prevent layout shifts. Self-host fonts rather than using Google Fonts (eliminates extra DNS lookups and connections). Preload WOFF2 font files with preload.

## Note

FOIT is invisible text; FOUT is unstyled text. FOUT is preferable for UX but can cause CLS. The best solution is optional + size-adjust overrides.

## In code

@font-face {
  font-family: 'Body Font';
  src: url('/fonts/body.woff2') format('woff2');
  font-display: optional;
  size-adjust: 90%; /* Matches fallback metrics */
  ascent-override: 85%;
}

@font-face {
  font-family: 'Display Font';
  src: url('/fonts/display.woff2') format('woff2');
  font-display: swap;
}

## Common questions

Q: Should I use swap or optional for body text?

A: optional is better for CLS because it eliminates the swap reflow. Swap is better if the brand font must always appear.

## Key takeaways

• Controls font rendering behavior during load.
• swap: show fallback text immediately.
• optional: use font only if cached.
• Always use size-adjust to prevent reflow.
• Prevents invisible text (FOIT).

## Related entries

• [CLS (Cumulative Layout Shift)](atomicglue.co/glossary/cls-cumulative-layout-shift)
• [Preload / Prefetch / Preconnect](atomicglue.co/glossary/preload-prefetch-preconnect)

Last updated July 2026. Permalink: atomicglue.co/glossary/font-display-swap