font-display optional and CLS

Definition

font-display: optional is the CSS property to reach for when you want to use a webfont (a font not built into the browser, downloaded separately via CSS @font-face) but want to prevent the screen from jolting once because the font arrives late.

More precisely, font-display is the policy that decides how the browser behaves while the webfont hasn't arrived yet. The optional value means "if it doesn't arrive within a short window (the block period, the grace time the browser waits for the font, usually around 100ms), just settle on the fallback font, and don't swap to the webfont on this page." The goal is to keep the layout from shifting, i.e., to lower CLS (Cumulative Layout Shift, a Core Web Vitals metric measuring how much page elements unexpectedly shifted).

Why it matters

Using swap, which is close to the default, this happens: the page is first drawn with the fallback font, and a moment later, when the webfont arrives, it swaps to that font. But the two fonts have different glyph metrics (the dimensions a single character occupies), so at the swap moment, tags (pill/badge) or line-break positions in the body shift. To the user's eye it looks like "the text jumps just as I'm about to finish reading," and this docks the CLS score.

For text-heavy UI like documents and lists, keeping the first screen from shifting is often more beneficial to user experience and Core Web Vitals (Google's key web-performance metrics) than showing the brand font 100%. optional locks that trade-off toward "no shift."

How it works

1. The browser waits for the webfont to load during a short block period.
2. optional: if it doesn't arrive within the period, it gives up the webfont for this navigation and settles on the fallback font.
3. The fallback font stack (the order of candidate fonts listed in font-family) renders all the way through, so dimensions don't change midway.
4. When testing on a slow network, confirm CLS stays close to 0.

Practical application

• Apply optional to the body, mono badges, and large titles (display) each. However, only the top hero (the large, most prominent area of the first screen) may be an exception with preload (<link rel="preload">, which tells the browser "fetch this font first" and raises its priority) and swap.
• Adding size-adjust (a @font-face property that proportionally adjusts the fallback font's glyph size to match the webfont) to the fallback font keeps glyph dimensions close to the webfont even when optional gives up the webfont.
• Under throttling that mimics a slow network (forcing the speed down to Slow 4G etc. in the browser dev tools), regression-check with Lighthouse that CLS doesn't degrade again.

Trade-offs

• optional lowers the ratio at which the brand font actually appears — only the hero area can be spared as an exception.
• On a first visit + slow 3G, you may see only the fallback font — a trade-off accepted in exchange for eliminating shift.

When not to use

• When brand typography is core to product identity, so showing that font 100% matters more than CLS.

Common mistakes

• Applying optional while the fallback font stack is just system-ui alone — the font shown instead of the webfont has poor legibility.
• Mixing swap and optional without a per-role policy, so some text shifts and some doesn't.

Related concepts

• [[cls-skeleton-layout-reservation]]
• [[critical-rendering-path]]