font-display: swap Explained: Stop Invisible Text While Fonts Load

What font-display does

When a page uses a web font, the browser has to decide what to show before the font file arrives. The font-display descriptor in @font-face controls that decision. It divides the font's loading time into a block period, when text using the font is invisible, and a swap period, when text is shown in a fallback font and replaced once the web font loads.

Without font-display, the browser uses auto, which in current browsers behaves like block. The result is a flash of invisible text (FOIT): headings and body copy stay blank until the font downloads or a timeout of about three seconds passes.

The five values

The timings are the values the CSS Fonts specification recommends; browsers may differ slightly.

What bseoa flags

bseoa reads the page's inline <style> blocks and reports this warning when an @font-face rule doesn't include font-display. Rules in external stylesheets need the same fix.

@font-face {
  font-family: 'Brand Sans';
  src: url('/fonts/brand-sans.woff2') format('woff2');
}

How to fix it

Add font-display to every @font-face rule:

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

For Google Fonts, add the display parameter to the stylesheet URL. Google then writes the descriptor into every @font-face rule it serves:

<link rel="stylesheet"
      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap">

If you self-host fonts loaded by a framework (Next.js next/font, Fontsource, a theme), check its font-display option. Many default to swap, but not all.

Does font-display: swap improve LCP?

Often, yes. Largest Contentful Paint measures when the largest element in the viewport is rendered, and on text-heavy pages that element is frequently a heading or paragraph. Text hidden during the block period isn't painted, so a slow font delays LCP. With swap, the fallback text paints almost immediately, and that paint counts.

The trade-off is layout shift. When the web font replaces the fallback, differences in character width and line height can move content and add to Cumulative Layout Shift. Two ways to reduce it:

• Preload the one or two fonts used above the fold so the swap happens early, ideally before first render: <link rel="preload" href="/fonts/brand-sans.woff2" as="font" type="font/woff2" crossorigin>.
• Adjust the fallback font's metrics to match the web font with the size-adjust, ascent-override and descent-override descriptors, so the swap barely moves anything.

@font-face {
  font-family: 'Brand Sans Fallback';
  src: local('Arial');
  size-adjust: 104%;
  ascent-override: 92%;
}

body {
  font-family: 'Brand Sans', 'Brand Sans Fallback', sans-serif;
}

The right percentages depend on the two fonts. Tools such as Fontaine and next/font calculate them automatically.