Core Web Vitals in Next.js

The tea shop, in three numbers

Three things decide how the tea shop feels to a visitor: how soon the main content shows, whether the page stays still while it loads, and how fast it answers a click. Google gives each one a number, and together they're called the Core Web Vitals: LCP for loading, CLS for staying still, and INP for answering. Google's tools report them, and Google Search uses them, among many other signals.

They're measured in the visitor's browser, while the page is open. Next.js gives you one hook to read them, useReportWebVitals. Here the tea shop shows every number the hook reports, in a list in the corner of each page. This is a real Next.js 16.4.3 project, built with next build, run with next start, and visited in real Chrome:

1"use client";2 3import { useCallback, useState } from "react";4import { useReportWebVitals } from "next/web-vitals";5 6type Metric = Parameters<Parameters<typeof useReportWebVitals>[0]>[0];7 8export function WebVitals() {9  const [metrics, setMetrics] = useState<Metric[]>([]);10  // The same function on every render, so the hook reports each metric once.11  const report = useCallback((metric: Metric) => {12    setMetrics((list) => [...list, metric]);13  }, []);14  useReportWebVitals(report);15 16  return (17    <ul aria-label="Web Vitals" style={{ position: "fixed", top: 0, right: 0 }}>18      {metrics.map((metric) => (19        <li key={metric.id}>20          {metric.name} on {new URL(metric.navigationURL).pathname}: {show(metric)} ({metric.rating})21        </li>22      ))}23    </ul>24  );25}26 27function show(metric: Metric) {28  return metric.name === "CLS" ? metric.value.toFixed(3) : `${Math.round(metric.value)} ms`;29}

app/web-vitals.tsx is a Client Component: line 1 is "use client", because the numbers only exist in the browser. Line 4 imports the hook from next/web-vitals. Line 9 keeps a list of metrics in state. Lines 11 to 13 make report, a function that adds one metric to the list, and line 14 hands it to the hook, which calls it once for each metric it has measured. Lines 17 to 23 show the list, and line 20 writes each metric as its name, its page, its value and a rating. Line 15 of app/layout.tsx renders WebVitals in the root layout, so every page is measured.

Open the Steps tab. Step 1 opens /, step 2 clicks Add Mint tea, and step 3 clicks Cart. After step 3, the list has five lines for /: the three Core Web Vitals, and two helpers that come first, TTFB (Time to First Byte: when the first byte of the HTML arrived) and FCP (First Contentful Paint: when the browser first drew any text or image). The sixth line, FCP on /cart, is the cart's own. In this recording, LCP on / was 600 ms (good), CLS 0.000 (good) and INP 96 ms (good). These are timings from one visit on one computer, so they change from run to run.

LCP, CLS and INP

Each metric watches one part of the visit:

• LCP, Largest Contentful Paint, is the time from the start of the visit until the biggest image or block of text in the window has been drawn. It's usually the hero photo or the main heading. In the first recording, the whole page was drawn in its first paint, so LCP equals FCP in that recording.
• CLS, Cumulative Layout Shift, scores how much visible content moves without the visitor asking for it. Each move scores how much of the window moved times how far it moved, and CLS is the worst burst of such moves during the visit. A move in the half second after a click or key press doesn't count: the visitor asked for that one. CLS has no unit.
• INP, Interaction to Next Paint, is the time from a click, tap or key press until the browser draws the next frame. It adds up three parts: the input delay, while the browser finishes other work before it can start your event handlers; the processing time, while the handlers run; and the presentation delay, while it lays out and draws the next frame. That frame doesn't have to show the answer: INP ends at the first paint after the interaction, whatever it shows. A visit can have many interactions; INP reports one close to the slowest. It replaced an older metric, First Input Delay (FID), in March 2024.

Each metric has two thresholds from web.dev, Google's site about web performance. Up to the first, the value is good. Up to the second, it needs improvement. Above it, it's poor. Each row is one metric:

The rating on each line of the tea shop's list comes from those thresholds: the hook works them out for you, as "good", "needs-improvement" or "poor". TTFB and FCP have ratings too, though they aren't Core Web Vitals: they help you find why LCP is slow.

A site isn't judged by one visit. Every visitor has another phone, network and patience, so the numbers spread out. Google judges each metric at the 75th percentile: line all the visits up from fastest to slowest, and take the value three quarters of the way along. If that value is good, at least 75% of visits were good. Phones and computers are judged separately.

Reporting them with useReportWebVitals

useReportWebVitals is a hook, so it must run in a Client Component. The docs suggest the shape the tea shop uses: a small file of its own with "use client" at the top, rendered once in the root layout. The layout stays a Server Component, and the client part is only that file and what it imports.

That file isn't free. Because it's in the root layout, every route loads its code and the web-vitals code it imports, and runs them after hydration. So keep it tiny: no UI library, no state it doesn't need, and nothing but the hook and the code that sends each metric away. The list in the tea shop's corner is there for the lesson; a real reporter, like the one below, renders nothing.

The hook calls your function with one object per metric. These are the fields you'll use most:

• name: "LCP", "CLS", "INP", "FCP" or "TTFB".
• value: the number, in milliseconds for all but CLS. rating: good, needs improvement or poor.
• id: different for each metric of each page load, so a server that gets the same metric twice can tell.
• navigationURL: the address the metric belongs to. The tea shop's list reads its path on line 20.

Keep the function the same from render to render. The docs warn that the hook calls a new function with the metrics measured so far, so a function written inline in the component would get them again on every render. Lines 11 to 13 of app/web-vitals.tsx use useCallback with no dependencies for that. A function outside the component works too.

When does each metric arrive? Look at the list after each step of the first recording again. Each row is one group of metrics:

The hook is short. In 16.4.3, it's packages/next/src/client/web-vitals.ts: an Effect that hands your function to onCLS, onLCP, onINP, onFCP and onTTFB from a copy of Google's web-vitals library that ships inside Next.js. That library listens to the browser's own measurements with a PerformanceObserver, such as its largest-contentful-paint and layout-shift entries, and turns them into the numbers above. The first four calls pass reportSoftNavs: true. A soft navigation is a page change without a new document, like the one a Link makes. The Chrome that made these recordings reports them, so clicking Cart ended the measurements for / and started new ones for /cart: that's where FCP on /cart comes from. In a browser that doesn't, everything after a client-side navigation still counts for the page the visitor opened first, and CLS and INP arrive when the tab is hidden or closed.

Sending them to your own server

A list on the page helps you learn; real visitors' numbers belong on your server, where you can add them up. Here the shop sends each metric to a Route Handler of its own:

1"use client";2 3import { useReportWebVitals } from "next/web-vitals";4 5type Metric = Parameters<Parameters<typeof useReportWebVitals>[0]>[0];6 7// Outside the component, so it's the same function on every render.8function send(metric: Metric) {9  const body = JSON.stringify(metric);10  // keepalive lets the request finish even when the visitor is leaving the page.11  fetch("/api/vitals", { method: "POST", body, keepalive: true });12}13 14export function WebVitals() {15  useReportWebVitals(send);16  return null;17}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (5/5)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ƒ /api/vitals└ ○ /cart ○  (Static)   prerendered as static contentƒ  (Dynamic)  server-rendered on demand $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ ReadyTTFB on /: 314 ms (good)FCP on /: 824 ms (good)LCP on /: 824 ms (good)FCP on /cart: 34 ms (good)CLS on /: 0.000 (good)INP on /: 88 ms (good)

In app/web-vitals.tsx, send on lines 8 to 12 sits outside the component, so it's the same function on every render. Line 9 turns the metric into JSON, and line 11 posts it to /api/vitals with fetch. keepalive: true lets the request finish even when the visitor is leaving the page, which is exactly when CLS and INP are often sent. The component returns null: it shows nothing. The docs' version uses navigator.sendBeacon, which also survives the page closing, and falls back to this fetch; here fetch lets the recording list each request.

In app/api/vitals/route.ts, line 6 prints each metric in the server's log. Open the Terminal tab: after the build comes what next start printed while real Chrome made the visit, one line per metric, in the order they arrived. The Steps tab has the POST /api/vitals requests that carried them.

Lab data and field data

Numbers like the ones above come in two kinds. Lab data comes from a test you run: one visit, on a device and network you pick. Field data comes from your real visitors, on their own phones and connections. Each row asks the same question of both:

The tea shop's recordings are lab data, and very little of it: one visit, in Chrome with no window, on a fast computer that was busy with other work, talking to a server on the same computer. They show what changes when the code changes, like the order in which Chrome asked for files, or whether the teas moved. They don't show what your visitors feel. A phone on a train can get bigger numbers.

Field data has two common sources:

• CrUX, the Chrome User Experience Report: Google's collection of real visits from Chrome users who agreed to share usage statistics, for public pages with enough visitors, over the last 28 days. PageSpeed Insights shows a page's CrUX numbers at the top and a Lighthouse lab run below them; Search Console has a Core Web Vitals report from the same data.
• Your own reporting, often called RUM (real user monitoring): useReportWebVitals sending to your server, like the tea shop's /api/vitals. It covers every page, including ones CrUX never sees, like pages behind a sign-in, and you can split the numbers by page, device or release.

Fixing a slow LCP

LCP is a chain. The HTML must arrive, the browser must ask for the LCP image (if it's an image), the file must download, and then it must be drawn. A delay anywhere in the chain makes LCP late. web.dev names the four parts: time to first byte, the delay before the image is asked for, the download, and the delay before drawing.

The second part is the one Next.js code changes most easily. Here the home page opens with a big photo of mint tea. On a fast connection, the difference is hard to see, so the recorder first made Chrome's network slow: each request waited 1.5 seconds, like a weak phone signal. Pick each version, then read step 2's list of requests and step 4's LCP:

1import Image from "next/image";2import { AddToCart } from "./add-to-cart";3 4const teas = [5  { name: "Green tea", price: 4 },6  { name: "Mint tea", price: 3 },7  { name: "Lemon tea", price: 3 },8];9 10export default function Home() {11  return (12    <main>13      <Image14        src="/mint-tea.jpg"15        alt="A cup of mint tea on a saucer"16        width={1600}17        height={1067}18        sizes="100vw"19        style={{ width: "100%", height: "auto" }}20      />21      <h1>Tea shop</h1>22      <ul>23        {teas.map((tea) => (24          <li key={tea.name}>25            {tea.name}: ${tea.price} <AddToCart name={tea.name} />26          </li>27        ))}28      </ul>29    </main>30  );31}

Without preload, the photo is lazy, like every next/image by default: the browser asks for it only after it has laid out the page and seen that the photo is on the screen. In step 2's list, the photo's request comes last, after the stylesheet and every script. With preload on line 20, Next.js puts a <link rel="preload" as="image"> in the head, and the photo's request comes right after the HTML. In this recording, LCP on / was 4,688 ms (poor) without preload, and 3,128 ms (needs-improvement) with it, in this recording only: the numbers change from run to run. What the playground shows is the order of the requests, and that preload beat the photo left lazy. It doesn't compare preload with the other two fixes below.

The real problem was the lazy default, and next/image gives three ways out. The docs say that in most cases, loading="eager" or fetchPriority="high" is the one to use:

• loading="eager": load the photo at once, wherever it is on the page. Fits a photo that is surely on the first screen.
• fetchPriority="high": ask the browser to fetch it before other images. Fits the photo that is most likely the LCP.
• preload: also put a preload link in the head, so the download starts before the browser reaches the <img>. Fits one photo that is surely the LCP on every screen size. Don't combine it with loading or fetchPriority, and don't use it on several photos that could each be the LCP.

In Next.js 16, preload replaced priority, which still works and is deprecated. Optimizing images shows the HTML each of the three writes. Preloaded files compete with each other, and with the page's other files, for the same network.

The other parts of the chain have their own fixes:

• A late first byte. If every request waits for slow data before any HTML is sent, everything is late. Keep the page's static shell prerendered, and let the slow part stream in behind a Suspense boundary (Partial Prerendering explains the shell).
• An LCP that needs JavaScript. A heading or photo that a Client Component fetches in an Effect can only be drawn after the JavaScript has loaded and run. Render it in a Server Component, so it's in the HTML.
• A heading in a web font. next/font preloads the font file and draws the text in a matched fallback until it arrives (Fonts in Next.js).
• A photo bigger than needed. sizes lets the browser pick a smaller file from the srcset, so the download is shorter.

Fixing layout shift

The tea shop now shows each visitor an offer, read from a cookie. The offer comes from a slow service, so it streams in a second after the rest of the page, behind a Suspense boundary. Before it arrives, the boundary shows its fallback. Pick each fallback, then read step 3's list:

1import { Suspense } from "react";2import { AddToCart } from "./add-to-cart";3import { Offer } from "./offer";4 5const teas = [6  { name: "Green tea", price: 4 },7  { name: "Mint tea", price: 3 },8  { name: "Lemon tea", price: 3 },9  { name: "Oolong", price: 5 },10  { name: "Chamomile", price: 4 },11  { name: "Jasmine", price: 5 },12];13 14export default function Home() {15  return (16    <main>17      <h1>Tea shop</h1>18      <Suspense fallback={<p>Loading your offer…</p>}>19        <Offer />20      </Suspense>21      <ul>22        {teas.map((tea) => (23          <li key={tea.name}>24            {tea.name}: ${tea.price} <AddToCart name={tea.name} />25          </li>26        ))}27      </ul>28    </main>29  );30}

In app/offer.tsx, Offer reads the cookie on line 5, waits a second on line 7, and returns a section with the class offer, which offer.module.css makes 300 pixels tall. With the one-line fallback on line 18 of app/page.tsx, the six teas sit right under Loading your offer…, and jump down when the offer takes its place. In this recording, CLS on / was 0.115 (needs-improvement). With OfferSkeleton, on lines 16 to 22 of app/offer.tsx, the fallback has the same class and the same height, so the teas start where they'll stay. CLS was 0.000 (good).

Both versions have something else in common. The offer's heading is the biggest text on the screen, and it arrives a second late, so LCP on / waited for it: 1,152 ms (good) and 1,376 ms (good). Streaming lets the rest of the page show at once; it doesn't make the streamed part sooner. When you can, keep the main content in the part that doesn't wait.

A skeleton is one fix. The others follow the same rule, keep room for what's coming:

• Fallbacks the size of their content: a loading.tsx or Suspense fallback with the page's own shape (Loading UI builds one).
• Images with their size: width and height, or fill in a box of a known size, so the browser keeps the photo's room before the file arrives (Optimizing images).
• Fonts with a matched fallback: next/font draws text in a local font resized with size-adjust until the web font arrives, so the lines don't change length when it swaps (Fonts in Next.js).
• Nothing pushed in above: a cookie banner or a late message goes over the page or at the end, not above content the visitor is already reading. The tea shop's own metrics list is position: fixed in the corner for the same reason: when it grows, nothing else moves.

A slow click and INP

After a click, the browser runs your event handler, then draws the next frame. Until the handler is done, it can't draw anything, so a handler that does a lot of work makes the click feel ignored. Here the Add button also updates a list of suggestions, which takes 300 ms of busy JavaScript. Pick each order of work:

1"use client";2 3import { useState } from "react";4 5export function AddToCart({ name }: { name: string }) {6  const [added, setAdded] = useState(false);7 8  function add() {9    updateSuggestions();10    setAdded(true);11  }12 13  return <button onClick={add}>{added ? "Added" : `Add ${name}`}</button>;14}15 16// Stands in for slow work, like sorting a long list of suggestions: 300 ms of busy JavaScript.17function updateSuggestions() {18  const end = performance.now() + 300;19  while (performance.now() < end) {}20}

With the work first, line 9 runs updateSuggestions before line 10 changes the state, and the browser paints Added only after both: the 300 ms are processing time, so INP can't be under 300 ms. With the paint first, line 9 changes the state, React updates the button, and line 11 waits: requestAnimationFrame runs just before the next frame is drawn, and the setTimeout inside it starts the work right after that frame. The work takes as long as before; it just no longer stands between the click and the next paint, so INP drops far below. In this recording only, INP on / was 440 ms (needs-improvement) with the work first and 72 ms (good) with the paint first; the numbers change from run to run. (The event loop explains how tasks and frames take turns.)

Other ways to keep clicks fast:

• Do less work in the browser: sort, filter or format on the server, where Server Components do it before the HTML is sent.
• Mark a slow re-render as a transition, so React can stop rendering it to handle the next click.
• Keep third-party scripts that keep the browser busy off the pages that don't need them.

Which number does it hurt?

Before launch, the tea shop's team lists what could go wrong. Each problem makes one metric worse. Sort them by the metric they hurt.

Common mix-ups

• "The Core Web Vitals come from Lighthouse." No. They're measured from real visits first. Lighthouse is a lab test of one visit, and it can't measure INP without clicks.
• "A good score on my laptop means visitors are fine." No. Your laptop is one fast visit. What counts is the 75th percentile of real visits, on slower phones and networks.
• "useReportWebVitals can go in a Server Component." No. The numbers exist only in the browser, so the hook runs in a Client Component: a small file of its own, rendered in the root layout.
• "Streaming always makes a page better." It shows the rest of the page sooner, but a fallback of the wrong size makes the page jump, and a streamed block that is the biggest thing on the screen delays LCP.
• "preload every image to be safe." No. Preload the one photo that is the LCP. Preloaded photos compete for the same connection, and lazy loading saves the others for visitors who scroll.
• "INP is the delay of the first click." That was First Input Delay, which INP replaced in 2024. INP looks at the whole visit, and at the time until the next paint, not only until the handler starts.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

LCP: 3,100 ms
CLS: 0.04
INP: 260 ms

Step 1: open /
Step 2: click Add Mint tea
Step 3: click Cart

"use client";

import { useState } from "react";
import { useReportWebVitals } from "next/web-vitals";

export function WebVitals() {
  const [count, setCount] = useState(0);
  useReportWebVitals((metric) => {
    console.log(metric.name, metric.value);
    setCount((n) => n + 1);
  });
  return <p>{count} metrics</p>;
}

"use client";

import { useCallback, useState } from "react";
import { useReportWebVitals } from "next/web-vitals";

export function WebVitals() {
  const [count, setCount] = useState(0);
  const report = useCallback((metric: { name: string; value: number }) => {
    console.log(metric.name, metric.value);
    setCount((n) => n + 1);
  }, []);
  useReportWebVitals(report);
  return <p>{count} metrics</p>;
}

import { Suspense } from "react";
import { AddToCart } from "./add-to-cart";
import { Offer } from "./offer";

const teas = [
  { name: "Green tea", price: 4 },
  { name: "Mint tea", price: 3 },
  { name: "Lemon tea", price: 3 },
  { name: "Oolong", price: 5 },
  { name: "Chamomile", price: 4 },
  { name: "Jasmine", price: 5 },
];

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <Suspense fallback={<p>Loading your offer…</p>}>
        <Offer />
      </Suspense>
      <ul>
        {teas.map((tea) => (
          <li key={tea.name}>
            {tea.name}: ${tea.price} <AddToCart name={tea.name} />
          </li>
        ))}
      </ul>
    </main>
  );
}

import { Suspense } from "react";
import { AddToCart } from "./add-to-cart";
import { Offer, OfferSkeleton } from "./offer";

const teas = [
  { name: "Green tea", price: 4 },
  { name: "Mint tea", price: 3 },
  { name: "Lemon tea", price: 3 },
  { name: "Oolong", price: 5 },
  { name: "Chamomile", price: 4 },
  { name: "Jasmine", price: 5 },
];

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <Suspense fallback={<OfferSkeleton />}>
        <Offer />
      </Suspense>
      <ul>
        {teas.map((tea) => (
          <li key={tea.name}>
            {tea.name}: ${tea.price} <AddToCart name={tea.name} />
          </li>
        ))}
      </ul>
    </main>
  );
}

import Image from "next/image";
import { AddToCart } from "./add-to-cart";

const teas = [
  { name: "Green tea", price: 4 },
  { name: "Mint tea", price: 3 },
  { name: "Lemon tea", price: 3 },
];

export default function Home() {
  return (
    <main>
      <Image
        src="/mint-tea.jpg"
        alt="A cup of mint tea on a saucer"
        width={1600}
        height={1067}
        sizes="100vw"
        style={{ width: "100%", height: "auto" }}
      />
      <h1>Tea shop</h1>
      <ul>
        {teas.map((tea) => (
          <li key={tea.name}>
            {tea.name}: ${tea.price} <AddToCart name={tea.name} />
          </li>
        ))}
      </ul>
    </main>
  );
}

import Image from "next/image";
import { AddToCart } from "./add-to-cart";

const teas = [
  { name: "Green tea", price: 4 },
  { name: "Mint tea", price: 3 },
  { name: "Lemon tea", price: 3 },
];

export default function Home() {
  return (
    <main>
      <Image
        src="/mint-tea.jpg"
        alt="A cup of mint tea on a saucer"
        width={1600}
        height={1067}
        sizes="100vw"
        style={{ width: "100%", height: "auto" }}
        preload
      />
      <h1>Tea shop</h1>
      <ul>
        {teas.map((tea) => (
          <li key={tea.name}>
            {tea.name}: ${tea.price} <AddToCart name={tea.name} />
          </li>
        ))}
      </ul>
    </main>
  );
}

"use client";

import { useState } from "react";

export function AddToCart({ name }: { name: string }) {
  const [added, setAdded] = useState(false);

  function add() {
    updateSuggestions();
    setAdded(true);
  }

  return <button onClick={add}>{added ? "Added" : `Add ${name}`}</button>;
}

// Stands in for slow work, like sorting a long list of suggestions: 300 ms of busy JavaScript.
function updateSuggestions() {
  const end = performance.now() + 300;
  while (performance.now() < end) {}
}

"use client";

import { useState } from "react";

export function AddToCart({ name }: { name: string }) {
  const [added, setAdded] = useState(false);

  function add() {
    setAdded(true);
    // Let the browser paint "Added" first, then do the slow work.
    requestAnimationFrame(() => setTimeout(updateSuggestions));
  }

  return <button onClick={add}>{added ? "Added" : `Add ${name}`}</button>;
}

// Stands in for slow work, like sorting a long list of suggestions: 300 ms of busy JavaScript.
function updateSuggestions() {
  const end = performance.now() + 300;
  while (performance.now() < end) {}
}

Check your understanding

Key takeaways

• LCP is when the biggest thing on the screen is drawn: good is 2.5 s or less.
• CLS scores content that moves without the visitor asking: good is 0.1 or less.
• INP is the time from a click, tap or key press to the next paint: good is 200 ms or less.
• Sites are judged at the 75th percentile of real visits, phones and computers separately.
• useReportWebVitals runs in a small Client Component in the root layout. Give it a function that stays the same between renders.
• Lab tests find problems; field data from CrUX or your own reporting says whether visitors feel them.
• Preload the LCP photo, give fallbacks and images their size, and let a click paint before slow work.

Coming next: Shrinking the JavaScript bundle. The less JavaScript a page loads, the sooner it can answer clicks.