Core Web Vitals

Core Web Vitals are Google's three user-centered page experience metrics: loading (LCP), responsiveness (INP) and visual stability (CLS). They are measured on real visits in the field and judged at the 75th percentile. This sheet covers what each one measures, its parts, the usual fixes, and how to collect it. Tools are on Measuring & profiling.

The three metrics

• p75: a page passes when 75% of its visits meet "good", assessed separately for mobile and desktop.
• Field data: the official numbers come from real Chrome users (CrUX) over a rolling 28 days. Lab tools can't give you field INP: a Lighthouse page load has no interactions (TBT is its proxy), and DevTools live metrics and Lighthouse timespan mode only measure your own clicks.
• Browser support: LCP and INP (Event Timing) are measurable in every engine since Safari 26.2 (December 2025; MDN marks both Baseline 2025). CLS's Layout Instability API is still Chromium-only. Only Chrome feeds CrUX; your own RUM sees the rest.
• INP replaced FID (First Input Delay) as a Core Web Vital in 2024 (Google switched on March 12). FID only measured the delay of the first input; it is retired.

LCP: Largest Contentful Paint

The render time of the largest image, text block or video poster visible in the viewport, relative to the start of navigation.

The browser reports a new candidate each time a bigger element paints, and stops at the first user interaction. The last candidate is the LCP.

Text LCP has no resource: its time is TTFB + render delay, often caused by web fonts blocking text (font-display) or by JS-rendered content. Image fixes in depth: CSS, images & fonts.

INP: Interaction to Next Paint

The time from a user's click, tap or key press to the next frame painted after the page handles it. Hover and scroll don't count. INP is (close to) the page's worst interaction: the slowest one, ignoring one outlier for every 50 interactions, so pages with lots of input aren't punished for a single hiccup.

import { yieldToMain } from "./yield";
 
button.addEventListener("click", async () => {
  button.classList.add("is-loading"); // visible update
  await yieldToMain(); // let input and rendering in
  saveDraft(); // heavy work in a later task
});

yieldToMain() is scheduler.yield() with a setTimeout fallback; it's on JavaScript & the main thread.

React renders and commits updates from a click or key press synchronously at the end of the event, so that JavaScript counts as processing duration; the browser's style, layout and paint of the resulting DOM is presentation delay. Mark non-urgent updates with startTransition so input stays responsive (Rendering strategies).

CLS: Cumulative Layout Shift

Each unexpected movement of visible content gets a layout shift score:

• Impact fraction: the share of the viewport covered by the unstable elements, before and after the move.
• Distance fraction: the largest distance moved, as a share of the viewport's biggest dimension.
• Shifts are grouped into session windows: shifts less than 1 s apart, capped at 5 s per window. CLS is the worst window's total, not the sum over the page's lifetime.
• Shifts within 500 ms of a click, tap or key press are expected and excluded (hadRecentInput). Scrolling and transform animations don't shift layout.

Supporting metrics

Useful for diagnosis; not Core Web Vitals themselves.

Soft navigations: in a single-page app, route changes don't reload the page, so classic LCP/CLS describe only the first load. Chrome 151 (July 2026) ships the Soft Navigations API (soft-navigation entries), and DevTools' live metrics report per soft navigation from Chrome 152. CrUX doesn't count them yet.

Where the numbers come from

Pages with too little traffic have no CrUX data. Collect your own RUM from the first release.

The web-vitals library

Google's ~2 KB library implements the metrics exactly as CrUX does (buffering, bfcache restores, prerendering, backgrounded tabs). Current major: v6 (2026). v5 removed onFID; v6 adds opt-in soft navigation reporting (reportSoftNavs) for single-page apps.

bun add web-vitals

import { onCLS, onINP, onLCP } from "web-vitals";
import type { Metric } from "web-vitals";
 
function report(metric: Metric): void {
  // name, value, rating, delta, id, navigationType
  console.log(metric.name, metric.value, metric.rating);
}
 
onLCP(report);
onINP(report);
onCLS(report);

Callbacks fire when the value is final (usually when the page is hidden), not on every change. Pass { reportAllChanges: true } while debugging.

Attribution build: same API from web-vitals/attribution, plus a metric.attribution object that says why (about 1.5 KB more):

Common mistakes

Recipes

Send vitals to your endpoint

Batch metrics and flush when the page is hidden; sendBeacon survives the page unloading.

import { onCLS, onINP, onLCP } from "web-vitals";
import type { Metric } from "web-vitals";
 
// the route pattern (/posts/[id]), not the raw URL, which
// can carry IDs or personal data
const route = document.documentElement.dataset.route ?? "?";
const queue = new Map<string, Metric>();
const add = (m: Metric) => queue.set(m.id, m);
 
function flush(): void {
  if (queue.size === 0) return;
  const body = JSON.stringify([...queue.values()].map(
    ({ name, value, rating, id }) =>
      ({ name, value, rating, id, route }),
  ));
  queue.clear();
  navigator.sendBeacon("/rum", body);
}
 
onLCP(add);
onINP(add);
onCLS(add);
addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") flush();
});
addEventListener("pagehide", flush); // fallback

Find the LCP element

Paste into the console, or ship it in a debug build: logs each LCP candidate as it appears.

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    const lcp = entry as LargestContentfulPaint;
    console.log("LCP candidate", lcp.startTime, lcp.element);
  }
}).observe({
  type: "largest-contentful-paint",
  buffered: true,
});

Log slow interactions with attribution

Which element was slow, and which phase to fix.

import { onINP } from "web-vitals/attribution";
 
onINP(({ value, attribution }) => {
  const { interactionTarget, inputDelay,
    processingDuration, presentationDelay } = attribution;
  console.table({
    value, interactionTarget, inputDelay,
    processingDuration, presentationDelay,
  });
}, { reportAllChanges: true });

Reserve space for late content

An ad or embed slot that can't shift anything, and an image with its aspect ratio known up front.

<div class="ad-slot" style="min-height: 250px">
  <!-- ad script fills this later -->
</div>
 
<img src="/hero.avif" width="1200" height="675"
     alt="Harbor at dawn" fetchpriority="high">

Log layout shifts and their sources

See which nodes moved, in the console, while you reproduce the jump.

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    const shift = entry as LayoutShift;
    if (shift.hadRecentInput) continue;
    const nodes = shift.sources.map((s) => s.node);
    console.log("shift", shift.value, nodes);
  }
}).observe({ type: "layout-shift", buffered: true });

LayoutShift isn't in TypeScript's lib.dom yet, so declare the fields you read:

interface LayoutShift extends PerformanceEntry {
  value: number;
  hadRecentInput: boolean;
  sources: { node: Node | null }[];
}

References

• MDN: Web performance (opens in a new tab), Largest Contentful Paint (opens in a new tab), Interaction to Next Paint (opens in a new tab), Cumulative Layout Shift (opens in a new tab)
• MDN: LargestContentfulPaint (opens in a new tab), LayoutShift (opens in a new tab), PerformanceEventTiming (opens in a new tab), PerformanceObserver (opens in a new tab), navigator.sendBeacon() (opens in a new tab)
• web.dev: Web Vitals (opens in a new tab), LCP (opens in a new tab), Optimize LCP (opens in a new tab), INP (opens in a new tab), Optimize INP (opens in a new tab), CLS (opens in a new tab), Optimize CLS (opens in a new tab), Defining the metric thresholds (opens in a new tab)
• GoogleChrome/web-vitals (opens in a new tab) (README: API, attribution build)
• Chrome for Developers: Chrome UX Report (opens in a new tab), CrUX methodology (opens in a new tab)
• W3C: Largest Contentful Paint (opens in a new tab), Layout Instability (opens in a new tab), Event Timing (opens in a new tab)