Back to the catalog

Knowing when a webfont has loaded

Typography & Colour

document.fonts with font-display

Baseline widely availablederived from web-features, captured 2026-09-20
  • Chrome60
  • Edge79
  • Firefox58
  • Safari11.1

Features it needs

These libraries were written to answer a question CSS could not: has this font arrived yet. document.fonts.ready resolves once loading settles, and document.fonts.load waits for one family, so the class-swapping dance has a direct replacement. Most uses do not need the question at all, because font-display decides what the browser paints while it waits, and swap is the behaviour the class was usually there to produce.

When this applies

Waiting on a webfont before doing something, or swapping a class once it loads.

The native approach

document.fonts with font-display
@font-face {
  font-family: "Inter";
  src: url("/inter.woff2") format("woff2");
  /* Paint the fallback now, swap when the real one lands. */
  font-display: swap;
}

MDN reference

When the dependency is still right

An answer that always says "the platform covers it" is worse than no answer. These are the cases where this one does not hold.

  • You correct the layout shift the swap causes by matching the fallback's metrics to the webfont. size-adjust does that and is Baseline. Its companions ascent-override and descent-override have not shipped in Safari at all, so a project tuning all three carefully is not a candidate.
  • You measure text and need the exact moment the family is usable for that measurement. document.fonts.load resolves for a family and size, and a canvas or a truncation measurement taken a frame early is silently wrong rather than visibly broken.
  • You load fonts from a provider through webfontloader's module system, such as Typekit or Fonts.com, where the library is fetching the stylesheet as well as watching it.
  • You depend on the per-stage classes these libraries add to the html element, wf-loading and wf-active among them, which stylesheets across the project may be keyed to.

Signs it was hand-rolled

No package is involved in any of these, so nothing would match in a package.json. If the code looks like one of them, this rule applies anyway, and the conditions above still decide.

  • a canvas or offscreen span whose width is measured repeatedly to work out whether a webfont has replaced the fallback
  • a setTimeout that adds a fonts-loaded class after a guessed delay, on the assumption the font has arrived by then

Packages this covers

Minified and gzipped, captured 2026-09-20.