CSS Reference ยท Typography
The font-display descriptor
Reference for the font-display descriptor in @font-face: auto, block, swap, fallback and optional, how block and swap periods work, and which to choose.
font-display is a descriptor inside an @font-face rule, not a property you set on elements. It tells the browser what to show while a web font file is still downloading, and what to do if it arrives late.
Without guidance, a page might show invisible text for a few seconds (a "flash of invisible text") or suddenly swap fonts and move the layout. The descriptor lets you choose a trade-off between a consistent look and readable text as early as possible.
@font-face { font-family: "Brand"; src: url("/fonts/brand.woff2") format("woff2"); font-display: swap; }
Try it
The descriptor changes timing, not appearance, so a live demo can only show the declaration. Test it by throttling the network in your browser's developer tools.
Syntax
font-display: auto | block | swap | fallback | optional;
| Initial value | auto |
| Applies to | The @font-face at-rule (descriptor) |
| Inherited | Not applicable |
| Animatable | No |
| Computed value | As specified |
Values
| Value | Description |
|---|---|
auto |
The browser's default, usually the same as block. |
block |
A short period of invisible text, then the fallback; the web font swaps in whenever it loads. |
swap |
Almost no invisible period. The fallback shows at once, and the web font swaps in whenever it loads. |
fallback |
A very short invisible period, then the fallback; the swap happens only if the font arrives within a few seconds. |
optional |
A very short invisible period, and the browser may skip the web font entirely, such as on slow connections. |
The exact lengths of the periods are up to the browser; the spec gives them only as "short" and "a few seconds".
Usage notes
swapfor body text. It makes content readable immediately, at the cost of a possible layout shift when the web font arrives.optionalfor performance. It avoids layout shifts at the risk that first-time visitors see the fallback. Combined with preloading it works well for important fonts.- Reduce the shift. Choose a fallback with similar proportions, and adjust it with the
size-adjust,ascent-override,descent-overrideandline-gap-overridedescriptors in the same rule. - Preloading. A
<link rel="preload" as="font" crossorigin>in the HTML starts the download earlier. See<link>. - Icon fonts.
blockis often better for icon fonts, since a fallback letter in place of an icon is confusing; real SVG icons avoid the problem. - Where it works. It is ignored in places where the descriptor is not allowed, such as a normal style rule.
Browser support
Supported in all current browsers; fallback and optional behavior details can differ slightly between engines.
Related
@font-facefont-familyfont-synthesis- Lesson: Web fonts