How web fonts load

Words that waited for their font

Ravi wants the Leaf and Kettle website to look like the shop. In the shop, the specials board is written in chalk, in round handwriting. So he picks Caveat, a free handwriting font, for the mint tea page. It's for the heading, the words about the tea, and the brewing steps. The shop's name at the top stays in the phone's own font. Phones don't come with Caveat, so the page has to download it.

He copies the CSS from a blog post. It ends with font-display: block. That line tells the browser what to show while the font downloads. The post says block makes sure the words never show in the wrong font. Asha opens the page on her phone, on a slow mobile link. The shop's name appears. Under it, nothing. A second later, all the words arrive at once, in Caveat.

Ravi changes one word: swap instead of block. Now the words come with the page, in her phone's own font, and turn into Caveat a second later. Why did one word make so much difference? And why did the font take so long?

The course loaded both pages three times in Chrome 157, on a phone's screen. It used DevTools' Slow 4G network, and made the CPU 4 times slower. It kept a picture of every frame Chrome drew.

1// When Asha saw the words on her phone, as recorded (ms after she opened the page)2const block = { pageShown: 1234, wordsShown: 2234 };3const swap = { pageShown: 1226, wordsShown: 1226 };4 5console.log(`block: the words came ${block.wordsShown - block.pageShown} ms after the page`);6console.log(`swap: the words came ${swap.wordsShown - swap.pageShown} ms after the page`);

• Line 1 is a comment. Times are in milliseconds (ms) after Asha opened the page. Of the three loads, these times come from the one whose font arrived in the middle.
• Line 2 is the page with block: the page showed at 1,234 ms, and the words at 2,234 ms.
• Line 3 is the page with swap: the page and the words both showed at 1,226 ms.
• Lines 5 and 6 print block: the words came 1000 ms after the page and swap: the words came 0 ms after the page.

With block, Asha looked at the shop's name and an empty page for a whole second. The words were already there, in their places, but invisible. With swap, she could start reading at once. Here is what her screen showed:

The rest of the lesson takes four questions, one section each:

• Why did the font come so late? Why fonts are discovered late.
• What exactly did Asha see? Invisible text and swapped text.
• What can font-display choose? The five font-display values.
• Can JavaScript help? The font loading API.

For the same story without a stopwatch, see Web fonts in the system design course.

Why fonts are discovered late

A web font is a font file the page downloads, like a picture. Ravi's CSS tells the browser about it in two parts.

1@font-face {2  font-family: "Caveat";3  src: url("caveat.woff2") format("woff2");4  font-display: swap;5}6h1, p, li { font-family: "Caveat", sans-serif; }

• Lines 1 to 5 are an @font-face rule: a description of one font. Line 2 gives it a family name, "Caveat".
• Line 3 says where the file is: caveat.woff2, next to the stylesheet. It also gives the format, WOFF2: a compressed format for fonts on the web. The next lesson covers it.
• Line 4 is font-display. It comes back in the next two sections.
• Line 6 uses the font. The heading, the paragraph and the list items ask for "Caveat", and if it isn't there, for the phone's sans-serif.

Notice what the rule doesn't do: it doesn't download anything. The font is fetched only when some text uses it. The CSS Fonts spec says the rule "is designed to allow lazy loading of font resources that are only downloaded when used within a document." A browser that fetched every font in a stylesheet, used or not, would break the spec.

So before it can ask for the font, the browser needs three things, in this order.

• The HTML, to find the link to the stylesheet. The HTML never names the font, so the preload scanner can't find it early.
• The stylesheet, to find the @font-face rule. It's render-blocking, so nothing is drawn before it arrives either.
• Some text that uses the font. The browser learns that when it works out each element's styles. web.dev puts it this way: the browser "does not download the web font until it is determined that the current page's layout needs it."

Here is the swap page on Asha's phone, from the same recording:

1// The swap page on Asha's phone, as recorded (ms after she opened the page)2const stylesheet = { asked: 599, arrived: 1179 };3const font = { asked: 1183, arrived: 2205 };4 5console.log(`The stylesheet took ${stylesheet.arrived - stylesheet.asked} ms`);6console.log(`The font was asked for ${font.asked - stylesheet.arrived} ms after that`);7console.log(`The font took ${font.arrived - font.asked} ms`);

• Line 2 is the stylesheet. Chrome asked for it at 599 ms, when it read the link in the HTML, and it arrived at 1,179 ms.
• Line 3 is the font: asked for at 1,183 ms, and in at 2,205 ms.
• Lines 5 to 7 print The stylesheet took 580 ms, The font was asked for 4 ms after that and The font took 1022 ms.

The font couldn't start until the stylesheet had come. Then it needed a second of its own. A trace is Chrome's own record of every task it ran. Chrome's trace shows the exact moment it began loading the font. It was inside a Recalculate style task: the step where Chrome works out every element's styles. Chromium's source calls this "a fast path of loading web font in style phase". You met the same wait in Remove render delay, where a heading's font was asked for right after its stylesheet.

What if no text needs a font until later? Ravi adds a bold version of Caveat, in a file of its own. It's for a tip that appears a few seconds after the page.

1@font-face {2  font-family: "Caveat";3  src: url("caveat-bold.woff2") format("woff2");4  font-weight: 700;5  font-display: swap;6}

It's a second @font-face rule for the same family. Line 3 points at its own file, and line 4, font-weight: 700, says this face is the bold one. Then a script adds the tip:

1setTimeout(() => {2  const tip = document.createElement("p");3  tip.innerHTML = "<strong>Ravi's tip:</strong> add a slice of lemon.";4  document.querySelector("main").append(tip);5}, 3000);

• Lines 1 and 5 wait 3,000 ms, counted from when the script runs.
• Lines 2 and 3 make a paragraph that starts with <strong> words. Bold text in Caveat needs the bold face.
• Line 4 adds the tip to the page.

The course recorded this page too. Chrome asked for the regular face at 1,186 ms, as before. It didn't ask for caveat-bold.woff2 until 4,229 ms, once the tip was on the page. For the first four seconds of the visit, nothing was fetched for the bold face, because nothing used it. Compare the versions here.

Why it matters: a web font waits for the HTML, the stylesheet and the styles, one after another. On Asha's phone it was asked for at 1,183 ms. Whatever font-display says, the words can't be in Caveat before the font arrives. Starting it sooner is the next lesson's job, and the last section here shows one way.

Invisible text and swapped text

While the font travels, the browser has words to draw and no font to draw them in. It can do one of two things. Chrome's docs name what each looks like:

• Invisible text. Hide the words until the font arrives. The docs call it "a flash of invisible text (FOIT)".
• Swapped text. Show the words now in a font the device already has: the fallback font. Then swap the web font in when it arrives. The docs call that "a flash of unstyled text (FOUT)".

Invisible text isn't missing text. The CSS Fonts spec says the browser draws it with a fallback "with the same metrics as the selected font face but with all glyphs "invisible" (containing no "ink")". A font's metrics are its sizes, and its glyphs are its letter shapes. The words take up exactly the room the fallback font would. Everything around them is in its place; you just can't see them. You've met this before, as the sign under a sheet in Remove render delay. The icons waiting in their places in SVG and icons were the same idea.

Which fallback? The spec says the first font in the element's font-family list that's already loaded. Ravi's rule lists "Caveat", sans-serif, so Asha saw her phone's sans-serif.

Look at the opening picture again. The two pages differed in three ways:

• When she could read. With block, at 2,234 ms. With swap, at 1,226 ms.
• LCP. The largest text on the page was the paragraph. Invisible words don't count for LCP, so with block it came at 2,236 ms, when the paragraph became visible. With swap, it came at 1,224 ms.
• Movement. Caveat is narrower than the phone's font. When it arrived, the first step fitted on one line instead of two, and the steps below it moved up. That's a layout shift. CLS, Cumulative Layout Shift, scores how much the page moved: with swap, the page's CLS was 0.01.

Block didn't avoid the shift. Its CLS was 0.0063, because the invisible words had been laid out in the fallback's sizes too. web.dev explains that block "requires laying out the page assuming the fallback fonts, even if the text itself is not shown". Making the fallback take up the same room as the font is the subject of lesson 20.3.

Why it matters: invisible text costs reading time and LCP, and swapped text costs a jump. Neither is free, but on a slow link, a second of blank page is the bigger cost for most text.

The five font-display values

font-display is the line in the @font-face rule that picks between invisible and swapped text, and for how long. The CSS Fonts spec describes it with a timer. It starts "At the moment the user agent first attempts to use a given downloaded font face". The user agent is the browser. In Chrome, that moment is when it begins loading the font. The timer runs through three periods.

• The block period. If the font hasn't arrived, the words are invisible. If it arrives, it's used.
• The swap period. If the font hasn't arrived, the words show in the fallback. If it arrives, it's swapped in.
• The failure period. If the font still hasn't arrived, the browser gives up on it. The fallback stays for the rest of the page's life, even if the font comes later.

Each value sets how long the first two periods last. Read the table across: what the spec suggests for each period, then what Chrome's source code does.

Chrome's numbers come from two timers in its source, set to 100 ms and 3,000 ms. Both start when it begins loading the font. auto is whatever the browser prefers. The spec notes that "Many browsers have a default policy similar to that specified by block." Chrome adds two rules. They only apply to auto.

• On a slow connection, no invisible words. If Chrome rates the connection 3G or slower, it shows the fallback at once. It also loads the font at its lowest priority. It tells the console: "Slow network is detected".
• Otherwise, at most 2 seconds. The words stay invisible until 3 seconds after the font started, or 2 seconds after the visit started, whichever comes first. The source calls the second a limit "Based on the "good" LCP value of 2500ms."

All five, on Asha's phone

1// Asha's phone, Slow 4G: when the words showed, and when Caveat did (ms after she opened the page)2const shown = {3  auto: { words: 1241, caveat: 2224 },4  block: { words: 2234, caveat: 2234 },5  swap: { words: 1226, caveat: 2221 },6  fallback: { words: 1313, caveat: 2229 },7  optional: { words: 1230, caveat: null },8};9 10for (const [value, { words, caveat }] of Object.entries(shown)) {11  console.log(`${value}: words at ${words} ms, Caveat ${caveat === null ? "never" : `at ${caveat} ms`}`);12}

• Lines 3 to 7 hold the times. Each value has two: when the words became readable, and when they turned into Caveat.
• Line 11 prints one line per value, from auto: words at 1241 ms, Caveat at 2224 ms to optional: words at 1230 ms, Caveat never.

Four findings:

• auto behaved like swap. DevTools' Slow 4G adds 562.5 ms of delay to every request. Chrome rates a round trip of 272 ms or more as 3G. The page reported a 3g connection, and Chrome asked for the font at its lowest priority.
• block hid the words for a second, until the font arrived. Its 3-second timer never ran out.
• fallback hid them only briefly, from 1,247 to 1,313 ms, then showed the phone's font. The font came well inside 3 seconds, so it was swapped in at 2,229 ms.
• optional never used Caveat. The font arrived after the words were first painted, so it wasn't used on this visit.

A font that comes very late

On Asha's phone, the font always came long before 3 seconds. To watch the timers run out, the course loaded the page again. This time it used DevTools' Fast 4G, which Chrome rates 4G. And the font's server waited 4 seconds before answering. The font then arrived at about 4.5 seconds.

1// Fast 4G, the font's server 4 seconds slow (ms after the visit started)2const late = {3  auto: { fontAsked: 383, fallbackShown: 2010 },4  block: { fontAsked: 378, fallbackShown: 3391 },5  fallback: { fontAsked: 385, fallbackShown: 503 },6};7 8for (const [value, { fontAsked, fallbackShown }] of Object.entries(late)) {9  console.log(`${value}: invisible until ${fallbackShown} ms, ${fallbackShown - fontAsked} ms after the font was asked for`);10}

• Lines 3 to 5 hold when Chrome asked for the font, and when the words first showed in the fallback.
• Line 9 prints auto: invisible until 2010 ms, 1627 ms after the font was asked for.
• Then it prints block: invisible until 3391 ms, 3013 ms after the font was asked for.
• Last comes fallback: invisible until 503 ms, 118 ms after the font was asked for.

block waited for its 3-second timer, plus the next frame. auto stopped at Chrome's 2-second limit, counted from the visit's start. fallback waited 100 ms, then showed the phone's font, and its swap period ended 3 seconds after the font was asked for. Caveat came after that, so it was never used. Here are the frames:

Other browsers use the same two lengths, a little differently. Firefox's settings gfx.downloadable_fonts.fallback_delay and fallback_delay_short are 3,000 and 100 ms: 3 seconds for auto and block, 100 ms for the others. So Firefox can hide the words for up to 100 ms even with swap, as the spec allows. WebKit, Safari's engine, gives auto and block 3 seconds, swap none, fallback 100 ms then 3 seconds, and optional 100 ms then nothing.

Pick a value to see its frames and numbers on both networks:

And optional? It didn't throw the font away. The course opened the optional page a second time in the same browser. The font came from the cache, 0 bytes over the network. The words were in Caveat from the first paint, at 617 ms. That's the spec's plan for optional: "If they return later, the desired font faces might have finished downloading".

Try the timers yourself. Drag the slider to change when the font arrives.

Why it matters: a slow font can cost your visitors their words, their layout, or nothing but a nicer look. font-display decides which. Leaving it out doesn't mean "no waiting": it means the browser's own rules.

The font loading API

So far, CSS decided when the font loaded. The CSS Font Loading API lets JavaScript decide, and reports how it's going. Its parts:

• document.fonts: the page's set of font faces. Each @font-face rule puts one in it.
• FontFace: one font face, made from JavaScript, like an @font-face rule.
• A face's status, which is "unloaded", "loading", "loaded" or "error", and its loaded promise, fulfilled when the font is ready.

1const caveat = new FontFace("Caveat", 'url("caveat.woff2") format("woff2")', { display: "swap" });2document.fonts.add(caveat);3console.log("Before load():", caveat.status);4caveat.load();5console.log("After load():", caveat.status, document.fonts.check("26px Caveat"));6caveat.loaded.then(() => {7  console.log("Loaded at", Math.round(performance.now()), "ms:", caveat.status, document.fonts.check("26px Caveat"));8});

• Line 1 makes a FontFace for the family "Caveat", from the same file, with display: "swap".
• Line 2 adds it to document.fonts. MDN says it "must be added to the set before it can be used for drawing."
• Line 3 prints its status. Making a face downloads nothing.
• Line 4 calls load(), which starts the download now.
• Line 5 prints the status again, and document.fonts.check(): whether text in 26px Caveat could be drawn now without a swap later.
• Lines 6 to 8 wait for the font, then print the time, the status and check() once more.

Ravi put this script in the page's head, before the stylesheet's link. He also took the @font-face rule out of the stylesheet. On Asha's phone, the console printed Before load(): unloaded, After load(): loading false and Loaded at 1615 ms: loaded true.

The script asked for the font at 608 ms, while Chrome was still reading the HTML. The trace shows it began inside Evaluate script, the task that runs a script. The stylesheet only arrived at 1,175 ms. The font was in at 1,601 ms, against 2,205 ms when it waited for the stylesheet. Pick FontFace in the head in the playground in the second section to compare.

Waiting for all the fonts

Sometimes you want to know when all the fonts are done, for example before you measure some text. That's document.fonts.ready: a promise the spec fulfills "when the document is done loading fonts".

document.fonts.ready.then(() => {
  console.log(`Fonts ready at ${Math.round(performance.now())} ms`);
});

Lines 1 to 3 print the time once the fonts are done. The course read ready twice on the page with Ravi's tip. It learned when to read it.

• Read at the very start, before any font was asked for, it was fulfilled at 603 ms. Nothing was loading yet, so there was nothing to wait for.
• Read right after the tip was added, it was fulfilled at 5,231 ms, once the bold face had arrived. Chromium's source explains why. Reading it makes Chrome work out styles and layout first. That "may trigger font loads, and replace |ready_| with a new Promise."

So read ready once the content is on the page. The spec warns it's "only fulfilled once, but further fonts may be loaded after it fulfills." Events help too. document.fonts fires a loading event when fonts start loading, and a loadingdone event when they finish. On the tip page, loadingdone came at 2,232 ms for the regular face and 5,231 ms for the bold one. But MDN's data says Safari never fires loadingdone, so ready is the safer choice.

Try the API in your own browser.

Why it matters: CSS finds a font late. A script can ask for it as soon as the HTML is read. It can also tell you exactly when the font has arrived.

Pick a font-display value for each text

For each piece of text, ask two questions. Does it make sense in another font? And should it move once a visitor is reading it?

Common mix-ups

• "An @font-face rule downloads the font." No. The font is fetched only when some text uses it. The bold face waited until the tip came, at 4,229 ms.
• "Invisible text takes no space." No. It's laid out in the fallback's sizes, with no ink. That's why block still shifted the page: CLS 0.0063.
• "Without font-display, the words show at once." No. You get auto, the browser's own rules. With a fast connection and a slow font, Chrome hid the words until 2,010 ms.
• "block hides the words until the font comes, however long that takes." No. After about 3 seconds, Chrome, Firefox and Safari show the fallback. With the late font, block showed it at 3,391 ms.
• "With optional, the font is wasted." No. The font is kept in the cache. On the second visit, the words were in Caveat from the first paint.
• "document.fonts.ready waits for every font the page will ever need." No. It's fulfilled when nothing is loading. Read at the very start, it was fulfilled at 603 ms, before any font was asked for.

Practice exercises

Answer each one first, then open the hints if you need them.

const blockPeriod = 3000;
const fontArrives = 4000;
const at = 3500;

const sees = at < blockPeriod ? "nothing" : at < fontArrives ? "the fallback" : "Caveat";
console.log(`At ${at} ms: ${sees}`);

const swapPeriodEnds = 3000;
const fontArrives = 2500;

console.log(fontArrives < swapPeriodEnds ? "Caveat swaps in" : "The fallback stays");

const caveat = new FontFace("Caveat", 'url("caveat.woff2") format("woff2")');
caveat.load().then(() => {
  console.log("Caveat is", caveat.status);
});

document.fonts.add(caveat);

Check your understanding

For each question, ask how far along its way the font was, and which period its timer was in.

Key takeaways

• A web font is fetched only when some text needs it, after the HTML, the stylesheet and the styles. That makes it late.
• While it travels, the words are either invisible, laid out but with no ink, or in a fallback font that swaps later.
• font-display sets the block, swap and failure periods. Chrome's timers are 100 ms and 3 seconds.
• auto is the browser's choice. Chrome hides the words at most until 2 seconds into the visit, and not at all on 3G or slower.
• FontFace and load() start a font from JavaScript. document.fonts.ready tells you when the fonts the page needs now are in.

Sources

The facts on this page come from these standards, docs and source code:

• CSS Fonts Module Level 4: font loading guidelines, W3C.
• Optimize web fonts, web.dev.
• Chromium 157: css_font_face.cc, loading a web font while working out styles, the Chromium project.
• CSS Fonts Module Level 4: the font display timeline, W3C.
• Ensure text remains visible during webfont load, Chrome for Developers.
• Largest Contentful Paint (LCP), web.dev.
• Optimize web fonts: font rendering, web.dev.
• CSS Fonts Module Level 4: the font-display descriptor, W3C.
• font-display, MDN.
• Chromium 157: font_resource.cc, the font timers, the Chromium project.
• Chromium 157: remote_font_face_source.cc, the period for each value, the Chromium project.
• Chromium 157: remote_font_face_source.cc, the slow network intervention, the Chromium project.
• Chromium 157: document_loader.h, the 2-second limit, the Chromium project.
• Chromium 157: network_state_notifier.cc, the connection type under DevTools' throttling, the Chromium project.
• Chromium 157: network_quality_estimator_params.h, the round trip that counts as 3G, the Chromium project.
• Firefox: nsFontFaceLoader.cpp, the font timers, Mozilla.
• Firefox: gfxUserFontSet.h, waiting before the fallback, Mozilla.
• Firefox: all.js, gfx.downloadable_fonts.fallback_delay, Mozilla.
• WebKit: CSSFontFace.cpp, fontLoadTiming, the WebKit project.
• CSS Font Loading Module Level 3, W3C.
• CSS Font Loading API, MDN.
• Chromium 157: font_face_set_document.cc, document.fonts.ready, the Chromium project.
• Chrome DevTools' network presets (NetworkManager.ts), the Chrome DevTools project.

Coming next: Smaller, faster fonts, also in Loading content fast: LCP. WOFF2, subsets and preloading make the font arrive sooner, so there's less to hide or swap.