Font Loading

---
name: font-loading
description: Load web fonts without layout shift by subsetting the file, setting font-display, preloading first-paint weights, and matching fallback metrics. Use when custom fonts cause invisible text, a flash of restyle, or a CLS spike.
---

# Font loading

Web fonts arrive after the HTML and CSS that reference them, so the browser must
choose: hide the text until the font loads, or show a fallback and reflow when
the real font swaps in. The first flashes invisible text, the second jumps the
layout. Load fonts so text is readable immediately and nothing moves when the
swap happens.

## Method

1. **Set `font-display` in every `@font-face`.** Use `swap` to show fallback
   text at once and swap later, or `optional` to skip the swap on slow
   connections. Never leave the default `block`, which hides text for the
   whole fetch.
2. **Preload the weights first paint needs.** Add
   `<link rel="preload" as="font" type="font/woff2" crossorigin>` for the one or
   two faces above the fold so the fetch starts before the CSS is even parsed.
3. **Subset to the characters you actually use.** Strip unused glyphs and
   scripts with `glyphhanger` or `pyftsubset`; a Latin-only subset can be a
   fraction of the full file. Split by script with `unicode-range` so only the
   needed subsets download.
4. **Ship woff2 and nothing else.** woff2 is the smallest format and universally
   supported. Drop woff, ttf, and eot fallbacks unless you must serve ancient
   browsers: fewer formats mean smaller CSS and one fetch per face.
5. **Match fallback metrics to kill the swap shift.** Set `size-adjust`,
   `ascent-override`, and `descent-override` on a fallback `@font-face`,
   or use a tool like Fontaine, so the fallback fills the same space and
   the swap does not move text.
6. **Self-host instead of a third-party origin.** Serving fonts from your own
   domain removes a cross-origin connection and DNS lookup from the critical
   path and avoids a render-blocking request to a font CDN.

## Signals

- Is text visible during the font load rather than blank?
- Are first-paint fonts preloaded, so the fetch is not discovered late?
- Does the shipped file carry only the glyphs the site uses?
- Does the fallback-to-webfont swap leave the layout unmoved?

## Boundaries

The layout-shift metric this feeds is web-vitals' CLS; right-sizing images that
also shift layout is image-optimization. Variable-font axes and icon fonts carry
separate tradeoffs. Delivery caching defers to cdn-strategy.