Which value should I use?

Swap for most text, paired with a fallback whose metrics are close. Optional where a mid-read shift is the worst outcome and the exact typeface matters less.

Why does my font download twice when I preload it?

Almost always a missing crossorigin attribute. Fonts are fetched in anonymous mode, so a preload without it is a different fetch than the real one.

How do I avoid the layout shift entirely?

Optional guarantees it within a page view. Short of that, a fallback with matching metrics — adjusted with the override descriptors — reduces it to almost nothing.

Glossary

font-display

The font-display descriptor tells the browser what to do with text whose web font has not arrived yet: show nothing and wait, or show a fallback and swap when the font loads. Neither is free — waiting delays the text, swapping shifts the layout when the metrics differ. The value determines which cost a visitor pays, and the default in most browsers is a short invisible period followed by a swap, which is frequently not what anyone chose.

What the values do

Block: text is invisible for a short period, then falls back. Suitable where the wrong font would be worse than no text, which is rare.

Swap: the fallback renders immediately and is replaced when the font arrives. Text is always readable and the layout may shift.

Fallback: a very short invisible period, then the fallback, and a swap only if the font arrives quickly. A compromise that limits both costs.

Optional: a very short invisible period, then the fallback, and no swap at all in that page view. The font may be used on the next visit from cache.

Auto leaves it to the browser, which in practice behaves close to block with a short timeout.

Why swap is usually right and not free

Invisible text is the worst outcome for a reader who arrived to read something, and it is what the default produces on a slow connection.

Swapping means the text is readable immediately, which is what a visitor came for.

The cost is a layout shift when the fallback and the web font have different metrics, and the shift is proportional to how different they are.

Which is why choosing a fallback with similar metrics matters as much as choosing the display value.

Metric override descriptors let a fallback be adjusted to match the web font's measurements, which reduces the shift to almost nothing.

Where optional makes sense

On body text where readability matters more than the exact typeface, and where a shift mid-read is the worst outcome.

The first visit shows the fallback and the font is cached, so subsequent visits use it from the start with no shift at all.

It is the only value that guarantees no layout shift from fonts, which is why it appears in advice aimed at that measurement specifically.

It is also the value most likely to produce a complaint from whoever chose the typeface.

What else affects font timing

Fonts referenced only from CSS are discovered late, after the stylesheet parses — which is what a preload declaration addresses.

A font preload without a crossorigin attribute results in the file being fetched twice, because the two fetches are not recognised as the same one.

Subsetting to the characters actually used reduces the file substantially, particularly for typefaces with large character sets.

Self-hosting removes a third-party connection from the path, which is usually worth more than any display value.

How it is observed

Web fonts referenced by the page are reported, along with their weight.

Preload declarations are compared against the resources really used, which is where a missing or malformed font preload appears.

Layout shift is measured as a rendering result rather than attributed to fonts specifically.

The descriptor itself is inside the stylesheet, so it is observed only where the stylesheet was fetched and read.

Frequently asked questions

Which value should I use?: Swap for most text, paired with a fallback whose metrics are close. Optional where a mid-read shift is the worst outcome and the exact typeface matters less.
Why does my font download twice when I preload it?: Almost always a missing crossorigin attribute. Fonts are fetched in anonymous mode, so a preload without it is a different fetch than the real one.
How do I avoid the layout shift entirely?: Optional guarantees it within a page view. Short of that, a fallback with matching metrics — adjusted with the override descriptors — reduces it to almost nothing.

Sources

VeriFixScan crawls a site and applies its checks to every page it reaches, keeping the evidence behind each finding. Scanning one website is free.

Scan a website