The web-vitals library

The metrics, measured the way Chrome does

Asha opens the mint tea page at Leaf and Kettle, on her laptop. The heading appears first, then the photo of the tea. She clicks Add to cart. A moment later she clicks a link to the next page, and she's gone.

Here is her visit, moment by moment, as the course recorded it in Chrome:

Five moments gave a number each, even the banner that pushed the photo down. But they weren't all sent at once. LCP waited for her click, and INP and CLS waited until she left.

Nobody from the shop was watching. So how fast did the page feel to Asha? And how did it feel to everyone else who visited today, each on their own phone or laptop?

Module 11 gave you the browser's raw tools for this. The browser writes everything it times into one logbook, the performance timeline. Its LCP entries are a commentator calling out the biggest runner so far. Event Timing times each click like a bell rung at a café counter, from the ring to the cup on the table.

From those entries, you could work out LCP, INP and CLS yourself. But every metric comes with fiddly rules:

• When does the commentator stop calling out runners?
• Which slow click counts for INP, and which ones are left out?
• Which layout shifts are grouped together for CLS?
• What if Asha switches tabs halfway, or comes back with the Back button?

Get one wrong, and your numbers won't match Chrome's. Is there a way to get Chrome's numbers without writing those rules yourself?

Yes. Google's Chrome team publishes a JavaScript library called web-vitals. Its README calls it "a tiny (~3K, brotli'd), modular library for measuring all the Web Vitals metrics on real users". Brotli is a way to compress text files before they travel, so the library adds about 3 kilobytes to a page. And it measures them "in a way that accurately matches how they're measured by Chrome."

Collecting numbers like these from real visitors is called real-user monitoring, or RUM. Real-user monitoring explains the idea. This module builds it, starting with the library.

Here is all the code a page needs. It follows the README's example for sending results to a server:

1import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";2 3function sendToShop(metric) {4  const body = JSON.stringify({ name: metric.name, value: metric.value, id: metric.id });5  navigator.sendBeacon("/collect", body);6}7 8onLCP(sendToShop);9onINP(sendToShop);10onCLS(sendToShop);11onFCP(sendToShop);12onTTFB(sendToShop);

• Line 1 loads five functions from the library, one per metric.
• Lines 3 to 6 make sendToShop. It gets one metric object. It turns the metric's name, value and id into text, and sends that to the shop's server.
• navigator.sendBeacon() posts a small piece of data to a server. MDN says it's "intended to be used for sending analytics data".
• Lines 8 to 12 hand sendToShop to each function. The library calls it back once that metric's value is ready.

The metric object's name says which metric it is, like "LCP". Its value is the number. You'll meet its other fields as the lesson needs them.

Where should the library load? Late is fine. It asks for buffered entries, which you met in The performance timeline, so it sees what happened before it loaded. The README even says it "should be deferred until after other user-impacting code has loaded."

To see when the reports really arrive, the course built a small copy of the mint tea page and put web-vitals 6.2.3 on it. Three things on the page are slow on purpose:

• The server holds the tea photo back for 300 ms.
• A 600 ms timer puts a "Free delivery" banner above the photo, and pushes the photo down.
• Add to cart's click handler keeps the main thread busy for 150 ms.

Then Playwright, a tool that drives a real browser, did what Asha did. It loaded the page, waited a second and a half, clicked Add to cart, and clicked the link away. It did this in Chrome, and in Playwright's builds of Firefox and WebKit, Safari's engine. Every report went to the course's server. Here is when Chrome's five reports arrived:

Why did some reports wait so long? The next section answers that.

The rest of the lesson answers four questions:

1. When does each callback run?
2. What made a number slow? That's the attribution build.
3. Can you hear every change? That's reportAllChanges.
4. What about Back, prerendering and background tabs?

onLCP, onINP, onCLS, onFCP, onTTFB

Each of the five functions takes a callback. The README says the library calls it "any time the metric value is available and ready to be reported." Ready means final: the value can't change any more.

The five metrics become final at different moments. A café manager filling in a card for each visit works the same way:

Reported while the page loads: FCP and TTFB

FCP, first contentful paint, is the moment the first text or image was painted. Once it has happened, nothing can change it. So the library reports it as soon as the browser's paint entry arrives.

TTFB, time to first byte, is when the first byte of the page arrived. That can't change either. But the library holds its report until the page has loaded. Its source says it waits "to ensure all properties of the navigation entry are populated." The navigation entry is the page's stopwatch record from The navigation timeline. Some of its times are only filled in at the load event.

1// Chrome, on Asha's visit: each metric's value, and when its callback ran, in ms.2const reports = [3  { name: "FCP", value: 72, reportedAt: 76.5 },4  { name: "TTFB", value: 6.4, reportedAt: 332.4 },5];6 7for (const { name, value, reportedAt } of reports) {8  console.log(`${name} was ${value} ms. Its report came ${(reportedAt - value).toFixed(1)} ms later.`);9}

• Lines 3 and 4 hold two of Chrome's reports: the metric's value, and the time its callback ran.
• Line 8 subtracts the value from that time: the gap between the moment it measured and its report.
• It prints FCP was 72 ms. Its report came 4.5 ms later. and TTFB was 6.4 ms. Its report came 326.0 ms later.

FCP was reported almost at once. TTFB waited about a third of a second, because the load event waited for the photo, and the server held the photo back. Why it matters: the TTFB report carries the whole navigation entry, in metric.entries. So you can send the connection and server times from lesson 5.1 along with it.

LCP: final at the first click or key press

LCP is the commentator from Paint, LCP, and layout shift APIs. She calls out the biggest element painted so far. She stops at the whistle: the visitor's first input. So LCP can't be final until the visitor does something.

The library listens for three things: a click, a keydown, or the page being hidden. The first of them ends LCP.

Even then, it doesn't report straight away. It waits for the browser's next idle moment, using requestIdleCallback(). That function asks the browser to run some code when it has nothing else to do. The library's source says it waits "to reduce potential INP impact": its own work shouldn't slow down the click that ended LCP. The wait is capped at 1 second. If the page is hidden first, it reports at once.

1// Chrome, on Asha's visit, in ms.2const lcp = { value: 344, reportedAt: 2669.2 };3const click = 1879.3; // Playwright clicked Add to cart4 5console.log(`The hero photo was painted at ${lcp.value} ms.`);6console.log(`Its LCP report waited for the click, then ${(lcp.reportedAt - click).toFixed(1)} ms more.`);

• Line 2 holds Chrome's LCP report. The photo was painted at 344 ms, and the callback ran at 2669.2 ms.
• Line 3 is when Playwright clicked Add to cart.
• Line 5 prints The hero photo was painted at 344 ms.
• Line 6 subtracts the click from the report's time. It prints Its LCP report waited for the click, then 789.9 ms more.

Chrome found its idle moment 789.9 ms after the click. Firefox found one 177 ms after its click. WebKit doesn't have requestIdleCallback(), so the library uses a plain timer there. WebKit's report came 152 ms after the click, just after the click handler's 150 ms of work.

INP and CLS: final when the page is hidden

A slow click can come at any moment. So can a layout shift. So INP and CLS can keep growing for as long as the page is open, like the open lines on the manager's card.

The README says CLS and INP "should be reported any time the page's visibilityState changes to hidden." A page is hidden when the visitor can't see it any more. They switched tabs, minimised the window, went to another page, or closed the tab. The browser then fires a visibilitychange event, and document.visibilityState becomes "hidden".

Why hidden, and not when the page closes? Chrome's Page Lifecycle guide says the change to hidden "is also often the last state change that's reliably observable by developers". On phones, people close tabs or the whole browser, and the page gets no other event. Lesson 5.1 showed the same problem with unload.

1// Chrome, on Asha's visit, in ms.2const leave = 2677.7; // Playwright clicked the link to the next page3const reports = [4  { name: "INP", value: 184, reportedAt: 2689.8 },5  { name: "CLS", value: 0.0468, reportedAt: 2689.9 },6];7 8for (const { name, value, reportedAt } of reports) {9  console.log(`${name} ${value}: reported ${(reportedAt - leave).toFixed(1)} ms after she clicked the link.`);10}

• Line 2 is when Playwright clicked the link to the next page.
• Lines 4 and 5 hold Chrome's INP and CLS reports, with the time each callback ran.
• Line 9 prints how long after the click each one came: INP 184: reported 12.1 ms after she clicked the link. and CLS 0.0468: reported 12.2 ms after she clicked the link.

Both came as the page was hidden: each report says the page's visibilityState was already "hidden" when it was sent.

If Asha had only switched tabs and come back, the library would have kept measuring. The README warns that the callback "might be called multiple times during the same page load." The reportAllChanges section shows how to handle that.

That's also why the shop's code uses navigator.sendBeacon(). It's like posting a sealed envelope as you walk out of the door: it still arrives after you've gone. The README picks it because it "supports sending data as the page is being unloaded." Sending performance data looks at it closely.

Firefox and WebKit sent INP too, but no CLS at all. CLS is built on the Layout Instability API, which only Chromium browsers have. The README lists onCLS() as "Chromium" only.

Here is every report from the recording. Start with Chrome: find the paint, the click, the moment the page was hidden, and the reports around them. Then try Firefox and WebKit.

The attribution build

Asha's LCP was 344 ms and her INP 184 ms. Both are good. But suppose they weren't. What would you fix? A number on its own can't tell you.

The library comes in two builds, two ready-made versions of its code. The standard build gives you the numbers. The attribution build adds a note to every report, in an object called attribution. The README calls it "potentially-helpful debugging information that can be sent along with the metric values".

To switch, change one line: import from web-vitals/attribution instead of web-vitals. The functions and callbacks stay the same. The notes cost some bytes, though. Compressed with Brotli, the standard build was 3,037 bytes and the attribution build 4,978. The course's page used the attribution build, so every recorded report has a note.

LCP, in four parts

LCP's note splits its time into four parts, one after the other:

• timeToFirstByte: from the start of the visit to the page's first byte.
• resourceLoadDelay: from the first byte until the browser started loading the LCP image.
• resourceLoadDuration: how long the image took to download.
• elementRenderDelay: from the image arriving until it was painted.

The four parts of LCP takes each one apart later in the course. Here they are for Asha's visit:

1// Chrome's LCP report on Asha's visit: 344 ms, cut into four parts (in ms).2const parts = {3  timeToFirstByte: 6.4,4  resourceLoadDelay: 19,5  resourceLoadDuration: 305.8,6  elementRenderDelay: 12.8,7};8 9const total = Object.values(parts).reduce((sum, time) => sum + time, 0);10const [biggest] = Object.entries(parts).sort((a, b) => b[1] - a[1]);11console.log(`The four parts add up to ${total.toFixed(1)} ms.`);12console.log(`The biggest is ${biggest[0]}: ${biggest[1]} ms.`);

• Lines 3 to 6 hold the four parts from Chrome's LCP report, in milliseconds.
• Line 9 adds them up. Line 10 sorts them, biggest first, and keeps the first one.
• Line 11 prints The four parts add up to 344.0 ms. That's the LCP itself.
• Line 12 prints The biggest is resourceLoadDuration: 305.8 ms.

So 305.8 of the 344 ms went on downloading the photo. That's the server holding it back for 300 ms. The note also named the element, #hero, and its file, hero.jpg. Why it matters: you now know to speed up that one image's download. A faster first byte or a quicker paint would barely move LCP.

INP, in three parts

INP's note splits the slowest interaction into the three waits from the café counter in Event Timing and INP:

• inputDelay: waiting for the cook to hear the bell, before the click's handlers start.
• processingDuration: the cook making the tea, while the handlers run.
• presentationDelay: waiting for the waiter's round, until the next frame is painted.

1// Chrome's INP report on Asha's visit: 184 ms, cut into three parts (in ms).2const parts = {3  inputDelay: 0.3,4  processingDuration: 151.1,5  presentationDelay: 32.6,6};7 8const total = Object.values(parts).reduce((sum, time) => sum + time, 0);9const [biggest] = Object.entries(parts).sort((a, b) => b[1] - a[1]);10console.log(`The three parts add up to ${total.toFixed(1)} ms.`);11console.log(`The biggest is ${biggest[0]}: ${biggest[1]} ms.`);

• Lines 3 to 5 hold the three parts from Chrome's INP report.
• Lines 8 and 9 add them up and find the biggest, as before.
• It prints The three parts add up to 184.0 ms. and The biggest is processingDuration: 151.1 ms.

Most of the time went on the click handler itself: the 150 ms of work behind Add to cart. The note named the element Asha clicked, #cart.

In Chrome, the note went one step further and named the script. Chrome has the Long Animation Frames API from Long Tasks and Long Animation Frames. So the note lists the long frames that overlapped the click. Its longestScript names the longest script in them: BUTTON#cart.onclick, during the processing part. Firefox and WebKit don't have long animation frames, so their notes named the button, but no script.

The picture puts both metrics side by side, to scale:

CLS: the biggest shift

CLS's note points at the single biggest layout shift. It names the first element that moved, #hero, and when: at 637.9 ms. That's just after the banner's 600 ms timer put it in. Lesson 11.3 showed that a shift's record names what moved, not what pushed it. So look just above the photo, and you find the banner.

reportAllChanges

The standard callback waits for the final value. While you're debugging, you may want to watch a value change as the page loads. For that, pass an options object as the second argument to any of the five functions: onLCP(sendToShop, { reportAllChanges: true }).

The course's page set up both kinds of callback for every metric. Here is what LCP's two callbacks got on Asha's visit:

1// Chrome, on Asha's visit: the LCP values each kind of callback got, in ms.2const standard = [344];3const everyChange = [72, 344];4 5console.log(`The standard callback got: ${standard.join(", ")}`);6console.log(`The reportAllChanges callback got: ${everyChange.join(", ")}`);

• Line 2 holds what the standard callback got: one value.
• Line 3 holds what the reportAllChanges callback got: two values.
• Lines 5 and 6 print The standard callback got: 344 and The reportAllChanges callback got: 72, 344.

The first LCP candidate was the heading, painted at 72 ms. The commentator called it out, and the callback ran. Then the photo was painted at 344 ms, and it ran again. Its last value, 344, is the one the standard callback got.

CLS went the same way: 0 at first, then 0.0468 once the banner pushed the photo down. FCP, TTFB and INP got one report each, because their values never changed after the first. That's the README's rule: "reportAllChanges only reports when the metric changes, not for each input to the metric." A new shift that doesn't raise CLS isn't reported. Neither is a click that doesn't raise INP.

Adding up changes with delta and id

When one metric can arrive several times, your server has to put the reports together. Two fields help:

• delta is how much the value changed since this callback's last report. The README: "The first time the callback function is called, its value and delta properties will be the same."
• id stays the same on every report one callback sends about one metric, on one visit.

1// The two LCP reports the reportAllChanges callback got on Asha's visit, in ms.2const reports = [3  { value: 72, delta: 72 },4  { value: 344, delta: 272 },5];6 7let sum = 0;8for (const { value, delta } of reports) {9  sum += delta;10  console.log(`value ${value}, delta ${delta}. The deltas so far add up to ${sum}.`);11}

• Lines 3 and 4 hold the two LCP reports, each with its value and its delta. Both carried the same id.
• Line 7 starts a running total at 0. Line 9 adds each delta to it.
• Line 10 prints value 72, delta 72. The deltas so far add up to 72. and value 344, delta 272. The deltas so far add up to 344.

Adding up the deltas with the same id gives the latest value. Why it matters: some analytics tools can't replace a number they already have. They can only add to it. The README says to send those tools the delta, and add up the deltas for each id. Tools that can replace a value just need the value and the id.

This matters even without reportAllChanges, because INP and CLS can be reported again each time the page is hidden.

Should you turn it on for real visitors? The README says "in general using reportAllChanges is not needed (or recommended) for measuring these metrics in production." The final values are the same either way: in the recording, every metric's last value matched in all three browsers. So use it while you debug.

Back/forward cache restores, prerendering, and hidden tabs

Asha's first visit was a plain load. Real visits aren't always. The course recorded three more kinds in Chrome:

• Back: after Asha left, Playwright pressed Back. Chrome showed the page again from its back/forward cache. Then she clicked Add to cart, and left again.
• Prerendered: another page asked Chrome to load the shop in advance, hidden, and then opened it.
• Background tab: a Meta-click (Command-click on a Mac) opened the shop in a new tab, behind the current one. Three seconds later, the tab was closed.

Here is what the library did with each one. The rest of this section takes them in turn:

Coming back with the Back button

The back/forward cache, or bfcache, keeps a page in memory after you leave it. web.dev calls it "a snapshot of the entire page in memory, including the JavaScript heap". The heap is the memory where the page's JavaScript keeps its objects. Press Back, and the browser shows the page again at once, without loading it.

So when Asha pressed Back, the page didn't load again, and its scripts didn't start over. The library had to notice the restore by itself. It listens for the pageshow event. web.dev explains: "The pageshow event has a persisted property, which is true if the page was restored from bfcache and false otherwise."

The library does the same. The README says that after a restore, "a new metric object is created with a new id (since back/forward cache restores are considered separate page visits)." Each report's navigationType says which kind of visit it belongs to:

1// Two FCP reports from Chrome: Asha's first visit, and the same page after she pressed Back. In ms.2const reports = [3  { navigationType: "navigate", value: 72 },4  { navigationType: "back-forward-cache", value: 17.9 },5];6 7for (const { navigationType, value } of reports) {8  console.log(`${navigationType}: FCP ${value} ms`);9}

• Lines 3 and 4 hold two FCP reports Chrome sent: one from the first visit, one after the restore.
• Line 8 prints each one: navigate: FCP 72 ms and back-forward-cache: FCP 17.9 ms.

The restore sent five reports of its own, each with a new id. TTFB was 0, because nothing came from the network. FCP was 17.9 ms and LCP 18.4 ms. There's no load to watch after a restore, so the library times each one from the restore to the next painted frame. INP was 152 ms, from Asha's second click on Add to cart. CLS was 0: the banner had gone in during the first visit, so nothing moved this time.

Why it matters: Chrome's own field data counts restores this way. web.dev says tools like the Chrome User Experience Report "treat bfcache restores as separate page visits in their dataset." So your numbers line up with Chrome's, and a fast restore isn't lost inside the first visit.

Opened after a prerender

Prerendering loads a page before the visitor asks for it. Chrome's docs say a prerender "behaves as if the page has been opened in an invisible background tab". When the visitor goes to the page, Chrome swaps it in. A site lists the pages it wants prerendered in speculation rules, a small block of JSON in a script tag.

While the page is prerendering, document.prerendering is true. When the visitor opens it, the page is activated. The prerenderingchange event fires, and the navigation entry's activationStart records when.

The visitor only starts waiting when they open the page. It's like a café that lays your table before you arrive: your wait starts at the door. Chrome's docs say Core Web Vitals "are measured based on activation time." So the library waits for activation, then subtracts activationStart from TTFB, FCP and LCP:

1// Chrome, the prerendered visit. Times in ms from when Chrome started loading the page, hidden.2const activationStart = 2462.7; // when the visitor opened it3const paint = 2504; // the first contentful paint4 5console.log(`FCP, counted from when the page was opened: ${(paint - activationStart).toFixed(1)} ms`);

• Line 2 is when the visitor opened the page, counted from when Chrome started loading it.
• Line 3 is when the page painted its first text or image, on the same clock.
• Line 5 subtracts one from the other. It prints FCP, counted from when the page was opened: 41.3 ms.

The prerendered page reported FCP and LCP of 41.3 ms, both with the navigationType "prerender". TTFB was 0: the first byte had arrived long before the page was opened. Why it matters: a visitor who opens a prerendered page barely waits, and your data shows exactly that.

Loaded in a background tab

The page loaded, and painted its first text at 28 ms. But it started out hidden, behind the tab Asha was reading.

How did the library know? Chrome writes a visibility-state entry in the performance timeline each time the page's visibility changes. In Chrome, each visit's first entry gave the state the page started in, at 0 ms. This tab's first entry said "hidden". The library takes the first hidden entry as the moment the page was first hidden. Then it only reports a paint that came before that moment:

1// Chrome, the background tab. Times in ms from the start of the visit.2const firstHidden = 0; // the first "hidden" visibility-state entry3const paint = 28; // the first contentful paint4 5if (paint < firstHidden) console.log("The page was visible when it painted: report FCP.");6else console.log("The page was hidden before it painted: no FCP.");

• Line 2 is when the page was first hidden: at 0, from the very start.
• Line 3 is when it painted.
• Lines 5 and 6 follow the library's rule: report the paint only if it came before the page was first hidden. It prints The page was hidden before it painted: no FCP.

So there was no FCP, and no LCP. There was no CLS either: the library only reports CLS for a visit that reported FCP. Its source says that's "to match the current behavior of CrUX". The tab sent TTFB, 2.5 ms, and nothing else.

web.dev says Google's tools leave these pages out of LCP, because a page loaded in the background "does not reflect the user-perceived load time." It's like a customer the manager didn't see come in: she can't say how long they waited, so she leaves those lines blank.

Firefox and Safari don't have visibility-state entries. There, the library falls back to a simpler check. Its source says: "If the document is hidden when this code runs, assume it was always hidden and the page was loaded in the background".

Here are the four kinds of visit side by side. Read each row across: the kind of visit, the navigationType its reports carried, and what the library did.

Which metric's attribution?

Each item below is a field from the attribution notes on Asha's visit in Chrome. Which metric's note did it come from? Sort each one into LCP, INP or CLS.

Common mix-ups

• "Each callback runs once, as soon as the page loads." No. FCP came at once, but LCP waited for the click. INP and CLS waited until the page was hidden, and they can come more than once.
• "reportAllChanges gives a different final value." No. It only changes how often you hear. LCP ended at 344 and CLS at 0.0468 either way.
• "After Back, the old metrics carry on." No. A restore counts as a new visit, with new ids and the navigationType "back-forward-cache".
• "A prerendered page counts from when it started loading." No. It counts from activationStart, when the visitor opened it.
• "Every browser reports CLS." No. Firefox and WebKit sent none: onCLS() is Chromium only.
• "A page that painted always reports FCP." No. The background tab painted at 28 ms and sent no FCP, because it started hidden.
• "The library must load first, or it misses the early entries." No. It reads buffered entries, so it can load late. The README says to defer it.

Practice exercises

Answer first, then use the hints.

// Firefox's LCP report on Asha's visit: 420 ms, cut into four parts (in ms).
const parts = {
  timeToFirstByte: 5,
  resourceLoadDelay: 92,
  resourceLoadDuration: 303,
  elementRenderDelay: 20,
};

const total = Object.values(parts).reduce((sum, time) => sum + time, 0);
const [biggest] = Object.entries(parts).sort((a, b) => b[1] - a[1]);
console.log(`The four parts add up to ${total.toFixed(1)} ms.`);
console.log(`The biggest is ${biggest[0]}: ${biggest[1]} ms.`);

// Chrome's INP report after Asha pressed Back: 152 ms, cut into three parts (in ms).
const parts = {
  inputDelay: 0.1,
  processingDuration: 150.6,
  presentationDelay: 1.3,
};

const total = Object.values(parts).reduce((sum, time) => sum + time, 0);
const [biggest] = Object.entries(parts).sort((a, b) => b[1] - a[1]);
console.log(`The three parts add up to ${total.toFixed(1)} ms.`);
console.log(`The biggest is ${biggest[0]}: ${biggest[1]} ms.`);

Check your understanding

For each question, ask yourself three things: when the callback runs, what the note says, and what kind of visit it was.

Key takeaways

• web-vitals measures LCP, INP, CLS, FCP and TTFB on real visitors, with Chrome's rules. You call one function per metric, with a callback.
• Each callback runs when its value is final. FCP comes at once, TTFB after load, LCP after the first click or key press, and INP and CLS when the page is hidden.
• The attribution build adds a note to every report. LCP and INP come split into parts that add up, with the element and, in Chrome, the script behind them.
• reportAllChanges calls back on every change, with the same final value. Use delta and id to put reports together.
• A restore and a prerender each count as their own visit, timed from when the visitor saw the page. A page that started hidden reports no FCP, LCP or CLS.

Sources

The facts on this page come from these docs and source files:

• web-vitals 6.2.3 README, Google Chrome.
• Navigator: sendBeacon() method, MDN.
• web-vitals 6.2.3 source: onFCP, onTTFB, onLCP, onINP and onCLS, Google Chrome.
• web-vitals 6.2.3 source: getVisibilityWatcher and whenIdleOrHidden, Google Chrome.
• Page Lifecycle API, Chrome for Developers.
• Back/forward cache, web.dev.
• Prerender pages in Chrome for instant page navigations, Chrome for Developers.
• Largest Contentful Paint (LCP), web.dev.

Coming next: Field data from every browser. Firefox and Safari now report LCP and INP too. You'll measure every engine, and see what Chrome-only data leaves out.