Skip to content
Tutorials Center
My learning

Topics

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.

CSS
@font-face {
  font-family: "Brand";
  src: url("/fonts/brand.woff2") format("woff2");
  font-display: swap;
}

Try it

Declaring font-display

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

CSS
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

  • swap for body text. It makes content readable immediately, at the cost of a possible layout shift when the web font arrives.
  • optional for 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-override and line-gap-override descriptors in the same rule.
  • Preloading. A <link rel="preload" as="font" crossorigin> in the HTML starts the download earlier. See <link>.
  • Icon fonts. block is 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.