CSS font-display Property

The CSS font-display descriptor controls how a custom web font behaves while it is still downloading: whether the browser shows fallback text right away, hides the text until the font arrives, or gives up on the font entirely. It is a descriptor used inside the @font-face rule — not a normal property you set on an element.

This page explains the loading problem font-display solves, walks through each of its five values, and gives practical advice on which one to choose.

Why font-display exists

Originally the web was limited to a handful of "web-safe" fonts installed on the user's machine. The @font-face rule changed that: you can ship your own font files and tell the browser where to download them. But font files can be large, and a download takes time. During that delay the browser has to decide what to render for any text in that font. There are two competing behaviors:

FOIT — flash of invisible text. The browser hides the text until the custom font finishes downloading. On a slow connection the user may stare at a blank page for seconds. This is the default in most browsers.
FOUT — flash of unstyled text. The browser immediately shows the text in a fallback font, then re-renders it once the custom font loads. The content is readable instantly, but it visibly "jumps" when the swap happens.

Neither is universally better, so font-display lets you tell the browser which trade-off you prefer.

The three font-display periods

Every value is defined in terms of three timeline periods that start when the font begins loading:

Block period — the text is rendered invisibly (it still takes up space). If the font loads during this period, it is used. If the period ends first, the browser falls back to a system font.
Swap period — the text is shown in a fallback font, but the browser will swap to the custom font the moment it finishes loading.
Failure period — the browser treats the font load as failed and keeps the fallback font, even if the font later arrives.

Each value simply chooses how long the block and swap periods last.

Initial Value	auto
Applies to	`@font-face` rule.
Inherited	No.
Animatable	No.
Version	CSS Fonts Module Level 4
DOM Syntax	object.style.fontDisplay = "swap";

Syntax

font-display: auto | block | swap | fallback | optional;

Because font-display is a descriptor, it lives inside an @font-face block alongside font-family and src:

@font-face {
  font-family: 'MyWebFont';
  src: url('myfont.woff2') format('woff2'),
       url('myfont.woff') format('woff');
  font-display: swap; /* show fallback text immediately, then swap in the font */
}

You then use the font as usual. The descriptor is read automatically when the font loads:

body {
  font-family: 'MyWebFont', Arial, sans-serif;
}

Values

Value	Block period	Swap period	What the user sees
`auto`	browser default	browser default	Whatever the browser prefers — usually behaves like `block`.
`block`	short (~3 s)	infinite	Invisible text first, then the font whenever it arrives (FOIT-leaning).
`swap`	none / tiny	infinite	Fallback text instantly, swapped for the custom font on load (FOUT).
`fallback`	very short (~100 ms)	short (~3 s)	Brief invisible text, then fallback; the font is only used if it loads quickly.
`optional`	very short (~100 ms)	none	Fallback if the font isn't already cached; no layout-shifting swap.

Exact period lengths are not fixed by the spec — each browser picks its own. The values above are the common defaults used by Chrome and Firefox.

Which value should you choose?

swap is the most popular choice for body text. Content is readable immediately, which is great for accessibility and perceived performance. The downside is a visible reflow when the font swaps in.
optional is the best choice when avoiding layout shift matters more than guaranteeing the font appears. The browser uses the custom font only if it can load almost instantly (typically from cache); otherwise it sticks with the fallback and never swaps. This keeps your Cumulative Layout Shift score low.
fallback is a middle ground: a short invisible window, then fallback, with a brief chance to swap. Good for fonts that are nice-to-have but not critical.
block suits icon fonts or branding where the wrong glyph (e.g. a fallback character instead of an icon) would look broken — you'd rather show nothing than the wrong thing.
auto leaves the decision to the browser and gives you no control, so it's rarely the deliberate choice.

font-display is a descriptor, not a property, so the initial and inherit keywords do not apply to it the way they do to regular CSS properties.

Browser support

font-display is supported in all modern browsers (Chrome, Edge, Firefox, Safari, and Opera). In browsers that don't recognize a given keyword the descriptor is simply ignored and the browser's default loading behavior applies, so it is safe to use without a fallback.

@font-face — the rule that defines a custom font and where font-display lives.
font-family — sets which font (including your fallback stack) an element uses.
font-weight — controls how bold the text appears.
font — the shorthand for several font properties at once.