What Is the font-display CSS Property? Complete Guide (2026)

font-display Values: Reference Table

How to Add font-display: Step by Step

1. Locate every @font-face rule in your CSS or the Google Fonts <link>.
2. Add font-display: swap; to each @font-face, or &display=swap to the Google Fonts URL.
3. Pick a fallback stack with similar metrics (for example system-ui, Arial, Georgia).
4. Use size-adjust, ascent-override, descent-override, and line-gap-override to size-match the fallback to the web font.
5. Preload the critical web font with <link rel="preload" as="font" type="font/woff2" crossorigin>.
6. Re-run an automated audit and confirm the "Ensure text remains visible" check passes.

Self-hosted font with size-matched fallback

@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter.woff2') format('woff2');
  font-weight: 100 900;
  font-style: normal;
  font-display: swap;
}

/* Size-matched fallback eliminates the CLS caused by the swap */
@font-face {
  font-family: 'Inter Fallback';
  src: local('Arial');
  size-adjust: 107%;
  ascent-override: 90%;
  descent-override: 22%;
  line-gap-override: 0%;
}

body {
  font-family: 'Inter', 'Inter Fallback', sans-serif;
}

Google Fonts URL with display parameter

<link
  rel="preconnect"
  href="https://fonts.gstatic.com"
  crossorigin
/>
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap"
/>

Common Mistakes

• Forgetting fallback fonts in the font-family stack — the browser still hides text if there is nothing to fall back to.
• Using font-display: block for body copy, which recreates FOIT.
• Mixing swap on the regular weight and auto on the bold weight, causing inconsistent loading behavior.
• Not preloading the LCP font, which delays the swap by hundreds of milliseconds.
• Using swap without size-adjust overrides — the font swap causes a layout shift and hurts CLS.
• Loading every weight and style when the page only uses one or two.

How to Test font-display

1. Open Chrome DevTools, throttle to "Slow 4G", and reload — text should never disappear.
2. Run an automated audit and check "Ensure text remains visible during webfont load".
3. In the Network panel, block the font URL and confirm the page is still readable with the fallback.
4. Measure CLS with the web-vitals library or the Performance panel — the font swap should contribute zero shift if overrides are tuned.
5. Use Font Style Matcher to dial in size-adjust values.

See our Cumulative Layout Shift guide for the full CLS picture.

FAQ

What is the recommended font-display value?

swap is the right default for body copy and headings. It guarantees text is visible immediately and the audit passes.

Does font-display: swap cause CLS?

Yes, unless the fallback font has matching metrics. Use size-adjust, ascent-override, descent-override, and line-gap-override on a local fallback @font-face to neutralize the shift.

What is the difference between fallback and optional?

fallback still tries to swap in the custom font for about 3 seconds. optional only swaps if the font is already cached or arrives within roughly 100ms — otherwise the user keeps the fallback for the entire page visit.

Should I preload web fonts?

Preload the one or two fonts that paint above the fold. Preloading every font wastes bandwidth and can delay other critical resources.

Does font-display work with Google Fonts?

Yes. Append &display=swap (or any other value) to the stylesheet URL. Google Fonts injects font-display into the @font-face rules it serves.

Why is auto sometimes worse than swap?

auto defers to the browser, which in Chrome and Firefox uses a 3-second invisible block period. That is the FOIT problem swap exists to solve.

Can I use font-display on icon fonts?

Use block for icon fonts — a fallback glyph is usually meaningless, so it is better to wait briefly than to flash the wrong character.

Does this affect AI search engines like ChatGPT and Perplexity?

Indirectly, yes. Slow font loading inflates LCP — a Core Web Vital — and pages with weaker Core Web Vitals tend to rank lower. AI search engines preferentially cite well-ranked pages, so a missing font-display can quietly lower the odds that ChatGPT, Perplexity, or Google AI Overviews pick your page when answering a query.