font-display

font-display is a CSS descriptor you put inside an @font-face block. It tells the browser what to show in the window between the moment text needs to paint and the moment your custom font finishes downloading. That gap is real. On a cold visit over a slow connection a 40KB WOFF2 file can take a full second to arrive, and the browser has to decide whether to hide the text, show a fallback, or keep waiting.

There are five values: auto, block, swap, fallback, and optional. Each sets two invisible timers, a block period and a swap period. auto hands the decision to the browser, and most browsers treat it like block. block hides the text for up to three seconds while it waits for your font. swap paints a fallback instantly and swaps the moment the real font lands. fallback and optional shrink both windows, and optional is the strictest of the five.

font-display is not a loading strategy. It downloads nothing, it does not preload, it does not touch network priority. People collapse it into the FOIT-versus-FOUT debate and stop there, as if the only choice is invisible text or a flash of the wrong font. The value that matters most, optional, sidesteps both by refusing to swap at all once the page has painted.

Here is what the values do in the wild. Google Fonts has appended &display=swap to its embed snippets since 2019, so most of the web ships swap by default. swap means zero block time and an unbounded swap window, which is why you watch a system font repaint into Inter or Roboto a beat after load. That repaint moves layout, and moved layout is scored.

Cumulative Layout Shift became a Core Web Vital in 2020 and a Google ranking signal in the 2021 page experience update. A font swap that nudges every paragraph down eats into your CLS budget of 0.1. This is where font-display: optional earns its keep. optional gives the browser roughly a 100 millisecond block period, and if the font is not already cached and ready, the browser uses the fallback for the entire page view and never swaps. Zero swap means zero font-driven CLS.

The catch with optional is that first-time visitors see your fallback font, not your brand font, for that whole session. The fix is a metric-matched fallback: pick a system font and use the size-adjust, ascent-override, descent-override, and line-gap-override descriptors so the fallback occupies almost the exact same box as the real one. Now the swap, when it comes, shifts nothing.

You do not compute those overrides by hand. Fontaine from the Nuxt team, Malte Ubl's fallback generator, and the capsize library all emit them, and Next.js baked the whole flow into next/font when it shipped in Next 13 in October 2022. next/font generates a size-adjusted local fallback for every Google and local font automatically, which is the single biggest reason CLS scores improved across the Next ecosystem.

So which value do you reach for. Use swap plus a metric-matched fallback for body copy, where being able to read the fallback immediately beats a flawless first paint. Use optional for anything where a late swap would be jarring or where CLS is a scored risk, and accept that some visitors never see your custom font on that first view.

Do not use block. A three second invisible-text window on a hero headline is worse than any fallback, and it wrecks Largest Contentful Paint. And do not reach for font-display alone to fix a slow font. If the file is important, preload it with rel=preload and self-host it, because the descriptor only decides what happens during the wait, not how long the wait lasts.

The honest read is that font-display is a confession that web fonts are always a bet on the network. You are choosing, ahead of time, who loses when the bet goes bad: the reader staring at blank space, or the brand flashing the wrong typeface for a second.

font-display does not make your font load faster, it decides who pays for it being slow.