Web Performance

The 30-second version

Your product page loads in under a second on your laptop. Then a colleague opens it on the bus: a blank screen, then text, then a photo that shoves the text down just as they tap "Add to cart", and the button seems to ignore them. Nothing is broken. The page is just slow in three different ways.

Together, these three are Google's Core Web VitalsCore Web VitalsGoogle's three user-experience metrics for web pages: LCP (how fast the main content appears), INP (how fast the page responds to input) and CLS (how much the layout jumps).. They're the most widely used definition of "fast" on the web, and Google Search uses them as one of its ranking signals. Watch one page load fail all three, then switch to the fixed version:

Your laptop is not your users

The most common performance mistake isn't a bad line of code. It's testing only on a fast laptop with fast Wi-Fi. A mid-range phone runs JavaScript several times slower, and a mobile connection can take 100–200 ms just to send a message to a server and get the reply back. In this topic's measurements we use a "slow 4G phone" profile: 150 ms per round trip, 1.6 megabits per second, and a CPU slowed down 4×. That's the kind of device that decides your scores.

This topic builds on How Browsers Render: it explains frames, the main thread, and why a <script> can block a page. You don't need to read it first; we link to the exact section whenever we lean on it.

Primer: from Enter to pixels

Every speed problem in this topic comes back to two costs. If you understand them, every fix that follows will feel obvious.

Cost 1: round trips

A round trip is one message going from the phone to a server and the reply coming back. Its duration is the round-trip time (RTT)Round-trip time (RTT)How long it takes for a message to go from one machine to another and for the reply to come back. Roughly 1 ms inside a data center, 70–150 ms across an ocean.. On office Wi-Fi to a nearby server it can be 10–20 ms. On a phone with a weak mobile signal, 150 ms or more is normal.

Before the browser can even ask for your page, it needs several round trips just to set up a connection:

1. DNSDNSThe Domain Name System: the internet's phone book that turns a name like example.com into an IP address your computer can connect to.: look up the server's address from its name (often one round trip, sometimes cached).
2. TCPTCPTransmission Control Protocol: delivers a stream of bytes between two programs reliably and in order, resending anything lost. HTTP/1.1, HTTP/2 and most databases run on it.: open a connection (one round trip).
3. TLSTLSTransport Layer Security: the encryption layer that makes HTTPS secure. It proves the server is who it claims to be and scrambles everything so nobody in between can read or change it.: agree on encryption for HTTPS (one round trip with TLS 1.3).
4. Send the request, wait for the server to build the page, and receive the first byte: one more round trip plus the server's own time. That moment is the time to first byte (TTFB)Time to first byte (TTFB)How long from sending a request until the first byte of the response arrives. At minimum one round trip, plus however long the server thinks..

Worked example. On the slow phone, 3 round trips × 150 ms = 450 ms just to connect. One more round trip plus 100 ms of server time puts the first byte of HTML at 700 ms. Nothing can appear on screen before that, no matter how small your page is. (DNS, TCP/IP and TLS explain each step in depth.)

Cost 2: bytes

Once the connection is open, bytes flow at the connection's BandwidthBandwidthHow much data a link can carry per second (e.g. 100 Mbit/s). It's the width of the pipe — different from latency, which is how long one drop takes to get through.. Network speeds are quoted in megabits per second, and file sizes in kilobytes. A byte is 8 bits, so divide by 8:

• 1.6 Mbit/s ÷ 8 = 0.2 MB/s = 200 KB per second.
• A 180 KB photo therefore needs about 0.9 s on its own, and longer when other files download at the same time and share the connection.

On fast Wi-Fi (50 Mbit/s ≈ 6,250 KB/s), the same photo takes about 30 ms. That's why a page can be instant on your laptop and slow on a phone: the phone pays far more for every round trip and every byte.

Then the browser discovers more files

The HTML is only the start. As it arrives, the browser's Preload scannerPreload scannerA fast secondary parser in the browser that skims the raw HTML ahead of the main parser, looking for URLs in src and href attributes to start downloading early. It can't see URLs that only exist in CSS or JavaScript. skims ahead for src and href URLs (stylesheets, scripts, images) and requests them right away. Some files are discovered later: a font is only requested once the CSS that mentions it has arrived and been applied, and it often lives on a different server, which means a brand-new connection.

Meanwhile, nothing is painted until the CSS has arrived, because stylesheets are Render-blockingRender-blockingStops the browser from drawing anything yet. Stylesheets in <head> are render-blocking: the browser won't paint until they arrive, to avoid flashing unstyled content. (How Browsers Render §04 shows why). The first paint of any text or image is called First Contentful Paint (FCP)FCP (First Contentful Paint)The time until the browser paints the first text or image of the page — the moment the screen stops being blank. A helpful early-warning metric, but not a Core Web Vital..

Here's that whole sequence for a small page, as a waterfall: one row per file, time running left to right. Switch between the two networks:

Read it top to bottom. The HTML row starts with purple (connecting) and grey (waiting for the server). The three files the preload scanner found all start together once the HTML arrives. The font starts last, after a second connection to fonts.example.com. And the hero image, the biggest file, finishes last: on the phone that's around 2.8 s, which is already worse than the 2.5 s LCP target.

So every loading fix in this topic does one of three things:

Core Web Vitals: LCP, INP and CLS

LCP: the biggest thing in view

As the page loads, the browser keeps track of the largest image or text block inside the visible area (the ViewportViewportThe visible area of the page in the browser window. On phones the meta viewport tag tells the browser to use the device width instead of pretending to be a desktop.). Each time a bigger one is painted, it becomes the new LCP candidate. The last candidate before the user first taps, clicks, types or scrolls is the page's LCP.

• What can be the LCP element: <img> elements, the poster image of a <video>, elements with a CSS background-image: url(…), and blocks of text such as a heading or paragraph.
• What can't: invisible elements (for example opacity: 0) and images with almost no detail, such as a solid-colour placeholder.
• In practice: on most pages the LCP element is an image (a hero imageHero imageThe big image at the top of a page (a product photo, a banner). It is usually the page's LCP element, so it's the most important image to load fast. or product photo). On text-heavy pages it's a headline or the first paragraph.

INP: the slowest response

Every click, tap and key press is an interaction (scrolling and hovering are not). For each one, the browser measures the time from the input until the next FrameFrameOne complete picture shown on the screen. Smooth motion is many frames per second, each slightly different, like the pages of a flip book. is painted. INP reports roughly the worst of those over the whole visit; on pages with many interactions, it skips one outlier for every 50 interactions, so a single freak hiccup doesn't decide it. §08 takes one interaction apart.

INP became a Core Web Vital in March 2024, replacing FID (First Input Delay), which only measured the waiting part of the first interaction. You'll still see FID in older articles and tools.

CLS: unexpected jumps

Each time visible content moves without the user asking for it, the browser scores that Layout shiftLayout shiftContent on screen jumping to a new position after it was shown — for example when a late image or web font pushes text down. Google's CLS metric measures it. by how much of the screen moved and how far. CLS adds up the shifts that happen close together and reports the worst such burst (§10 does the arithmetic). Movement within half a second after a tap or key press doesn't count, because the user caused it, and neither do transform animations (CSS that moves an element visually, like sliding it in, without changing the layout around it).

Why the 75th percentile?

You can't judge a page by one visit: the same page is fast on a laptop on fibre and slow on an old phone on a train. Google collects the metric from many real visits and takes the 75th PercentilePercentileThe value below which a given share of measurements fall: p50 is the median; p99 is the value that 99% of requests are at or under. Used for latency because averages hide slow outliers.: sort all the visits from fastest to slowest, and take the value three quarters of the way along. 75% of visits were at that value or better.

Why not the average? An average mixes fast and slow visits into one number, so it can look fine while a quarter of your visitors wait 4 s or more. It can't tell you how many people had a bad time; a percentile can. And why not the worst visit? Because one user on a broken connection would make every page "poor". The 75th percentile is the compromise. Mobile and desktop are judged separately, and your mobile number is almost always the worse one.

Measuring: lab vs field, PerformanceObserver and web-vitals

Lighthouse runs a page load without clicking anything, so it can't measure INP. Instead it reports Total Blocking Time (TBT)TBT (Total Blocking Time)A lab metric: during page load, add up the part of every long task beyond 50 ms. Lighthouse uses it as a stand-in for responsiveness, because a lab test has no real clicks to measure.: during the load, it adds up how far each Long taskLong taskAny single piece of main-thread work that runs longer than 50 ms. While it runs, the page can't draw new frames or respond to clicks. ran past 50 ms. A high TBT means the main thread is often busy, which is the main cause of bad INP. It's a hint, not the real thing.

Asking the browser directly

The browser measures all three vitals itself. You can listen with a PerformanceObserverPerformanceObserverA browser API that calls your function whenever the browser records new performance entries of a type you ask for, e.g. largest-contentful-paint, layout-shift or event.: you tell it which entry type you care about, and it calls you back with each new entry.

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    // each entry is a new, bigger LCP candidate
    console.log("LCP candidate at", Math.round(entry.startTime), "ms:", entry.element);
  }
}).observe({ type: "largest-contentful-paint", buffered: true });

let cls = 0;
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.hadRecentInput) cls += entry.value;   // ← shifts right after user input don't count
  }
}).observe({ type: "layout-shift", buffered: true });

The widget below runs that exact code inside a tiny shop page, in a sandboxed iframeiframeAn HTML element (<iframe src=…>) that shows another web page inside a rectangle of the current page. The framed page keeps its own origin, so the outer page can't read inside it if it comes from elsewhere. (a separate document, so it gets its own LCP and CLS). Load it with "no size" and "inserted late", then fix one thing at a time:

Notice three things:

1. LCP changes its mind. The first candidate is usually the paragraph of text, painted early. When the image arrives, it's bigger, so it replaces the text as the LCP element.
2. An image without width and height causes a shift when it loads, because the browser didn't know how much space to keep for it. With the attributes, the space is reserved from the start and the image arriving moves nothing.
3. The late banner shifts everything below it, unless its slot was reserved.

In production: the web-vitals library

Getting these numbers exactly right is harder than the snippet suggests: CLS windows, the INP outlier rule, pages restored from the back/forward cache, tabs opened in the background. Google's web-vitalsweb-vitals (library)A small JavaScript library from Google (npm: web-vitals) that measures LCP, INP, CLS, FCP and TTFB in real users' browsers the same way Chrome does, handling the many edge cases for you. library (a few KB compressed; the whole of version 6 is about 3 KB with Brotli) implements all of that and reports each metric the same way Chrome does.

import { onCLS, onINP, onLCP } from "web-vitals";

function send(metric) {
  const body = JSON.stringify({
    name: metric.name,        // "LCP" | "INP" | "CLS"
    value: metric.value,      // ms for LCP and INP, a unitless score for CLS
    rating: metric.rating,    // "good" | "needs-improvement" | "poor"
    page: location.pathname,
  });
  navigator.sendBeacon("/analytics/vitals", body);  // ← still delivered if the tab is closing
}

onLCP(send);
onINP(send);
onCLS(send);

Store each beacon with the page, device type and country, and compute the 75th percentile per page and device. Observability covers percentiles and dashboards; §13 covers what to collect so you can find causes, not just scores.

LCP: find the hero, then make it early and small

LCP in four parts

1. Time to first byte: until the HTML starts arriving. Fix on the server: caching, a CDNCDNContent Delivery Network: servers spread around the world that keep copies of your files close to users, so they're served from a nearby city instead of your origin server. close to users, less work per request (Caching).
2. Resource load delay: from the first byte of HTML until the browser requests the image. It's large when the image is discovered late. Target: close to zero.
3. Resource load duration: downloading the image's bytes. Fix: fewer bytes (§06), and less competition from other downloads.
4. Element render delay: the image has arrived but isn't painted yet, because a stylesheet or script is still blocking rendering, or because JavaScript hasn't created the element yet.

In DevTools' Performance panel, the LCP marker on the timeline shows which element it was, and recent versions of Chrome show these four parts directly. In code, the element field of the largest-contentful-paint entry from §04 tells you.

A measured experiment

We built a small article page: a heading, a 1200 × 800 JPEG hero image (180 KB), 150 KB of JavaScript, a long article, and six 88 KB photos far below the foldAbove / below the foldAbove the fold = what's visible on the first screen without scrolling. Below the fold = everything you only see after scrolling. The name comes from newspapers, where the top half of the front page shows when folded. (thousands of pixels down, so nobody sees them without scrolling a long way). Then we loaded variants of it in Chromium with a slow-4G phone profile and measured LCP. Click through the variants in order:

Measured on this machine: headless Chromium 153, HTTP/2, network emulation 150 ms round trip and 1.6 Mbit/s, 4× CPU slowdown, 412 × 915 window. Individual loads varied by up to about ±0.2 s.

Three lessons, in order of size:

• On a slow network, bytes are time. The two biggest wins removed bytes: not downloading invisible photos (−2.7 s), and a smaller file for the hero (−1.2 s). Every byte downloading at the same time as the hero competes with it.
• Late discovery delays the request. A lazy hero waits for layout, a CSS background waits for the stylesheet (the Preload scannerPreload scannerA fast secondary parser in the browser that skims the raw HTML ahead of the main parser, looking for URLs in src and href attributes to start downloading early. It can't see URLs that only exist in CSS or JavaScript. only reads HTML), a JavaScript-inserted image waits for the script. In our test the LCP cost was modest (0.1 s), because the hero was sharing bandwidth anyway. With a bigger JavaScript bundle, a slower CPU, or the image on another server, the delay grows one-for-one.
• preload rescues late discovery when you can't put the <img> in the HTML (for example, a single-page appSingle-page app (SPA)A web app that loads one HTML page and then changes the view with JavaScript as you navigate, instead of loading a new page from the server each time. that renders everything with JavaScript).

The checklist for the LCP image

<img
  src="/img/kayak-800.avif"
  srcset="/img/kayak-400.avif 400w, /img/kayak-800.avif 800w, /img/kayak-1200.avif 1200w"
  sizes="(min-width: 700px) 50vw, 100vw"
  width="1200" height="800"
  fetchpriority="high"
  alt="Two-seat kayak on a calm lake">

• In the HTML, as a real <img>, so the preload scanner finds it in the first bytes.
• Never loading="lazy" on it. Lazy loading is for images below the fold.
• width and height so its space is reserved (CLS, §10).
• Right-sized and in a modern format with srcset (§06).
• fetchpriority="high"fetchpriorityAn HTML attribute (high, low or auto) on images, scripts and links that tells the browser how important a download is compared with others of the same kind., so the browser treats it as the most important image from the start.

<head>
  <link rel="preload" as="image" href="/img/kayak-800.avif" fetchpriority="high">
</head>

When the LCP element is text

If the largest element is a heading or paragraph, there's no image to download: LCP waits for the HTML, the render-blocking CSS, and possibly a Web fontWeb fontA font file (usually .woff2) the page downloads with @font-face, instead of using fonts already installed on the device.. The fixes are a fast TTFB, small critical CSSCritical CSSThe small amount of CSS needed to draw the first screen. Keeping it small (or inlining it in the HTML) means the first paint doesn't wait for a big stylesheet. (the CSS needed for the first screen; How Browsers Render §04), and a font strategy that doesn't hide text (§07). If your page's content is built by JavaScript in the browser, LCP also waits for that JavaScript to download and run; Rendering Strategies compares sending ready-made HTML from the server instead.

Images: formats, srcset, lazy loading

Images are usually the heaviest part of a page. In the HTTP Archive's yearly reports, images make up a large share of a typical page's bytes (often 40% or more). That makes them the easiest place to save.

1. The format

An image formatImage format (codec)How a picture is compressed into bytes. JPEG and PNG are old and universal; WebP and AVIF are newer and usually make photos much smaller at the same visual quality. decides how the pixels are compressed. We encoded the same test photo at five widths, with commonly used quality settings:

Measured on this machine with Pillow 12 (libjpeg, libwebp, libavif) on a synthetic, detailed landscape test image. When we instead tuned each format to the same measured quality, the gap was similar: WebP 46% and AVIF 54% smaller than JPEG at 1200 px. Published comparisons on real photos usually find WebP about 25–35% smaller than JPEG and AVIF around 50% smaller, so expect less than our synthetic image shows, and measure your own.

To serve AVIF with a fallback for older browsers, use <picture>. The browser takes the first <source> whose type it supports and falls back to the <img>:

<picture>
  <source type="image/avif" srcset="/img/lake-800.avif">
  <source type="image/webp" srcset="/img/lake-800.webp">
  <img src="/img/lake-800.jpg" width="1200" height="800" alt="A lake between green hills">
</picture>

In practice, a build step (for example the sharp library) or an image CDNCDNContent Delivery Network: servers spread around the world that keep copies of your files close to users, so they're served from a nearby city instead of your origin server. that converts on the fly produces these files for you. You write the markup once.

2. The size: srcset and sizes

A phone shows a full-width image about 360–430 CSS pixels wide. But phones have dense screens: the device pixel ratioDevice pixel ratio (DPR)How many real screen pixels make up one CSS pixel. A typical laptop is 1 or 2, most phones 2–3. A 400-CSS-pixel-wide image on a DPR 2 phone needs 800 real pixels to look sharp. is usually 2 or 3, meaning each CSS pixel is 2×2 or 3×3 real pixels. So:

Worked example. 400 CSS px × DPR 2 = 800 real pixels needed. From the table above, an 800-px JPEG is 88 KB. Without srcset, the same phone would download the 2400-px version made for big screens: 639 KB, over 7× more, for no visible difference.

srcset and sizessrcset and sizesTwo <img> attributes: srcset lists the same picture at several widths (photo-800.jpg 800w, …) and sizes says how wide the image will be shown. The browser combines them with the screen's pixel density and downloads one file. let the browser choose:

• srcset="lake-400.jpg 400w, lake-800.jpg 800w, …" lists the files and their real widths (the w means "this file is 400 pixels wide").
• sizes="(min-width: 700px) 50vw, 100vw" says how wide the image will be shown: half the window (50vw) on screens at least 700 px wide, otherwise the full window width. The browser needs this because it picks the file before your CSS has been applied.

The browser multiplies the shown width by the device pixel ratio and picks the smallest listed file that's big enough. Try it in your own browser:

<img src="photo-800.jpg" alt="…"
     srcset="photo-400.jpg 400w, photo-800.jpg 800w, photo-1200.jpg 1200w,
             photo-1600.jpg 1600w, photo-2400.jpg 2400w"
     sizes="100vw">

3. The timing: lazy loading

loading="lazy" tells the browser not to download an image until it's close to being scrolled into view. It's one attribute and saves every byte of every image the user never scrolls to.

<img src="/img/review-photo.jpg" width="600" height="400" loading="lazy" alt="Customer photo">

• Use it for images below the foldAbove / below the foldAbove the fold = what's visible on the first screen without scrolling. Below the fold = everything you only see after scrolling. The name comes from newspapers, where the top half of the front page shows when folded.: galleries, long lists, comment avatars, footer logos. In §05 this alone cut LCP from 4.8 s to 2.1 s, because six invisible photos stopped competing with the hero.
• Never on the LCP image or anything visible on the first screen: lazy images wait for layout before they're requested (§05 measured the delay).
• "Close to view" is generous. Chromium starts loading lazy images well before they scroll into view, roughly 1,250–2,500 px away depending on the connection. That's why the §05 test page has a long article between the hero and the gallery: when we first tried it with the gallery only about 300 px below the first screen, the "lazy" photos were still requested straight away. Lazy loading helps most on long pages.

<iframe loading="lazy"> works the same way, and is great for embedded videos and maps.

4. Space: always set width and height

Give every <img> its width and height attributes (the file's real pixel size is fine) and let CSS scale it:

img { max-width: 100%; height: auto; }   /* scales down, keeps the shape */

From the two numbers the browser works out the image's aspect ratio (its shape, here 3:2) and reserves the right amount of space before a single byte arrives. Without them, the image starts at zero height and pushes everything below it down when it loads: a layout shift (§10). For boxes without an image file (an embed, an ad slot), the CSS aspect-ratio: 16 / 9 property does the same job.

Fonts without the flash or the jump

Why fonts are always late

Look back at the waterfall in §02: the font was the last file to start. A browser only requests a font when both of these are true:

1. The CSS containing the @font-face rule has downloaded and been parsed.
2. Some text on the page actually uses that font. (The browser won't download fonts nobody needs, so it waits until it has matched styles to elements.)

That puts the font request after the HTML and after the CSS: two steps behind. If the font lives on another server, add a fresh connection (three round trips, §02).

What does the text do meanwhile?

Browsers have two choices while the font downloads, and both have a name (FOIT and FOUTFOIT / FOUTFlash Of Invisible Text (text hidden until the web font arrives) and Flash Of Unstyled Text (text shown in a fallback font, then swapped). font-display chooses between them.):

• Hide the text (a Flash Of Invisible Text): the page has blank spaces where words should be.
• Show it in a fallback font (a Flash Of Unstyled Text), then swap when the real font arrives.

The CSS property font-displayfont-displayAn @font-face setting that decides what text looks like while a web font downloads: invisible for a while (block), fallback right away (swap), or a compromise (fallback, optional)., inside the @font-face rule, picks the behaviour. The CSS spec defines it as two time windows: a block period (text is invisible) and a swap period (fallback text is shown and the real font may still replace it). Once the swap period is over, the page keeps the fallback, even if the font arrives later.

We measured the jump

A test page with a heading and two paragraphs in a web font ("Brand", an 80 KB TrueType file), a newsletter box below them, and DejaVu Sans as the fallback. Same slow-4G profile as §05:

Measured on this machine (headless Chromium 153, Slow-4G emulation, 412 px wide window), median of 3; every run gave the same CLS.

Read it row by row:

• block shifted just as much as swap. The invisible text still takes up space, laid out with the fallback font's sizes. When the real font arrives, the lines re-wrap and the newsletter box moves. Hiding text doesn't prevent the jump; it only hides the words.
• 0.039 from one font is 39% of the whole "good" CLS budget of 0.1, on a page with only two paragraphs.
• Preload started the download about 170 ms earlier. The font still swapped in, just sooner.
• Two setups removed the shift: optional (by never swapping late) and a fallback font scaled to match the web font's size (by making the swap move nothing).

Fix 1: preload the one or two fonts the first screen needs

<link rel="preload" href="/fonts/brand-latin.woff2" as="font" type="font/woff2" crossorigin>

Preload only what the first screen uses: every preload competes with the LCP image for bandwidth (the waterfall in §12 shows the trade).

Fix 2: a fallback that takes the same space

The jump happens because the fallback's letters are a different width and height from the web font's. You can scale a local fallback font to match, with size-adjustsize-adjustAn @font-face setting (with ascent-override and descent-override) that scales a fallback font so its letters take up the same space as your web font, so the swap doesn't move the text. and its friends:

@font-face {
  font-family: "Brand";
  src: url("/fonts/brand-latin.woff2") format("woff2");
  font-display: swap;
}

/* A local font, resized to take up the same space as Brand */
@font-face {
  font-family: "Brand Fallback";
  src: local("Arial");
  size-adjust: 92%;          /* scale the letters */
  ascent-override: 95%;      /* space above the baseline */
  descent-override: 25%;     /* space below it */
}

body { font-family: "Brand", "Brand Fallback", sans-serif; }

The numbers depend on the two fonts (the ones above are only examples; we found 82% for our pair by measuring). Tools such as Capsize or fontaine, and frameworks like Next.js's font module, calculate them from the font files for you.

Fix 3: fewer, smaller font files

• WOFF2 only. WOFF2WOFF2The standard compressed file format for web fonts. Supported by every current browser; there's no need to ship older formats. is compressed and supported by every current browser; skip .woff, .ttf and .eot.
• Subset. A full font may contain thousands of characters for many languages. Keep only what you use, and split by script with unicode-range so the browser downloads, say, the Cyrillic file only if the page contains Cyrillic text.
• Fewer weights. Each weight and style (regular, bold, italic) is usually its own file. A variable font holds a whole range of weights in one file; that's a win if you use three or more.
• Self-host. Since 2020–2021, all major browsers keep a separate HTTP cache per site, so a font from a shared font service is not reused across sites any more. Hosting it yourself removes a connection to another server (and a third-party dependency). If you keep a font service, preconnect to its file server (§12).

INP: from tap to next paint

Back in the shop: you ask the clerk a question. First you wait while they finish a phone call (input delay). Then they look up the answer (processing). Then they turn around and tell you (presentation). You only care about the total, but each part has a different fix.

How Browsers Render §08 showed the rule behind all of this: the Main threadMain threadThe single browser thread that runs your JavaScript and also does style, layout and most painting. While it's busy with a long task, the page can't respond to clicks or update. runs one task at a time, and the screen is only redrawn between tasks. Here's what that means for one tap:

1// already running: a 140 ms timer callback
2setTimeout(sendAnalyticsBatch, 0);
3 
4button.addEventListener("click", () => {
5  const cart = addToCart(item);   // 120 ms
6  badge.textContent = cart.count; // DOM write
7});

Now click a real one

This button's handler is a plain DOM listener that does exactly what the toggles say. The numbers come from your browser's Event Timing APIEvent Timing APIThe browser API behind INP. For each slow event (click, key press, tap) it records when the input happened, when your handlers started and ended, and when the next frame was painted., the same data INP is built from:

Try the three experiments one at a time:

1. Idle, 10 ms, one line. Every part is small; the total is a few dozen milliseconds, well under 200. That's a good interaction.
2. Background work on. Your handler didn't change, but now most clicks land while another 150 ms task is running, and the yellow input-delay part jumps. INP problems are often caused by code that has nothing to do with the thing the user clicked.
3. 3,000 items. The handler is still fast, but the browser must style, lay out and paint 3,000 new elements before it can show the frame: the cyan presentation part grows. (Parsing the new HTML happens inside the handler, so the pink processing part grows a little too.)

Reading Event Timing entries yourself

new PerformanceObserver((list) => {
  for (const e of list.getEntries()) {
    if (!e.interactionId) continue;                         // not part of a click, tap or key press
    const inputDelay   = e.processingStart - e.startTime;
    const processing   = e.processingEnd - e.processingStart;
    const presentation = e.startTime + e.duration - e.processingEnd;
    console.log(e.name, Math.round(e.duration), "ms =", inputDelay, "+", processing, "+", presentation, e.target);
  }
}).observe({ type: "event", durationThreshold: 40, buffered: true });

Fixing INP: paint first, yield, do less

Pattern 1: paint the feedback, then do the work

INP stops counting at the next frame after your handlers finish. If the handler does a small visible change and then yields, that frame shows the change quickly, and the heavy work continues in a later task.

button.addEventListener("click", () => {
  const cart = addToCart(item);      // 120 ms
  badge.textContent = cart.count;
  button.textContent = "Added ✓";
});

button.addEventListener("click", async () => {
  button.textContent = "Adding…";    // cheap, visible
  await yieldToMain();               // ← usually lets the browser paint "Adding…"
  const cart = addToCart(item);      // 120 ms, in a new task
  badge.textContent = cart.count;
  button.textContent = "Added ✓";
});

export function yieldToMain() {
  // scheduler.yield() resumes your code before other queued tasks (Chromium 129+).
  if (globalThis.scheduler?.yield) return scheduler.yield();
  return new Promise((resolve) => setTimeout(resolve, 0));   // a new task everywhere else
}

The user still waits 120 ms for the final result, but they see a response at once, and INP measures that first frame.

Be careful what you conclude, though: after the yield, addToCart is still one 120 ms long task. A second tap that arrives during it waits, exactly as before. To keep the page responsive throughout, split the work itself into chunks with a yield between them:

// the click handler now does: const cart = await addToCart(item);
async function addToCart(item) {
  const cart = loadCart();
  for (const step of [validate, reserveStock, updateTotals, saveDraft]) {  // ~30 ms each
    step(cart, item);
    await yieldToMain();                    // ← a gap after every chunk
  }
  return cart;
}

Pattern 3's table ("One long loop") lists more ways to cut work into pieces.

Pattern 2: in React, mark the slow update as a transition

In React, a state update inside an event handler is urgent by default: React re-renders and commits before the browser paints. If the update re-renders a big list, every key press pays for the whole list. A transitionTransition (React)A state update marked as non-urgent with startTransition or useTransition. React may delay or interrupt rendering it so urgent updates, like typing, stay fast. tells React that part of the update can wait:

import { memo, useState, useTransition } from "react";

export function Search() {
  const [text, setText] = useState("");     // what's in the box
  const [query, setQuery] = useState("");   // what the list filters by
  const [isPending, startTransition] = useTransition();

  function onChange(e) {
    setText(e.target.value);                            // urgent: show the letter now
    startTransition(() => setQuery(e.target.value));    // can wait, can be interrupted
  }

  return (
    <>
      <input value={text} onChange={onChange} />
      {isPending && <span>updating…</span>}
      <ProductList query={query} />
    </>
  );
}

const ProductList = memo(function ProductList({ query }) { /* renders hundreds of rows */ });

Feel the difference. Type "kayak" quickly in each mode:

Measured on this machine (production build, headless Chromium 153, typing "kayak" at one key per 120 ms): with plain setState each key press took 256–296 ms; with startTransition, 24–56 ms.

The list does the same total work in both modes. The transition only changes when it runs: after the letter has been painted, in slices small enough that the next key press never waits long. useDeferredValue(query) is the same idea from the receiving side: the list gets a copy of query that is allowed to lag behind.

Pattern 3: do less, or do it elsewhere

Pattern 4: shrink other people's tasks (input delay)

Input delay comes from whatever else is running when the user taps. The usual suspects on a real site:

• Third-party scriptsThird-party scriptJavaScript loaded from someone else's server — analytics, ads, chat widgets, A/B testing. It runs on your main thread with your page's permissions, and you don't control its size or speed.: tag managers, A/B testing, chat widgets, ads. Each one runs on your main thread. Load them with async or defer, delay non-essential ones until after the page is interactive, and remove the ones nobody uses.
• Hydration: when a server-rendered React page becomes interactive, React runs every component once, often as one long task. A tap during it waits. Rendering Strategies covers options that hydrate less, or in pieces.
• Big JavaScript evaluation while the page loads: §11 shows how to ship less of it.

CLS: how shifts are scored, and how to stop them

Back in the shop: you reach for a jar, and someone pushes the whole shelf down a row. You grab the wrong jar. On a page, that's tapping "Cancel" because "Buy" just moved under your finger. That's why CLS exists.

Scoring one shift

When something on screen moves to a new position between two frames, without the user asking for it, the browser computes two numbers:

• Impact fraction: the area of the Impact regionImpact region (CLS)In one layout shift, the union of the moving content's old and new visible areas: everything it covered before or after. Where old and new overlap, that area counts once. (everything the moving content covered, before or after the move; an area covered both times counts once) divided by the ViewportViewportThe visible area of the page in the browser window. On phones the meta viewport tag tells the browser to use the device width instead of pretending to be a desktop.'s area.
• Distance fraction: how far it moved, divided by the viewport's longest side.

Worked example. A phone viewport is 360 × 640 CSS pixels. A 300 px tall block of text starts at y = 140. A 120 px banner is inserted above it, so the block now spans y = 260 to 560. Together, the old and new positions cover y = 140 to 560: 420 px of height, the full width. Impact = 420 × 360 ÷ (360 × 640) = 0.656. Distance = 120 ÷ 640 = 0.1875. Score = 0.656 × 0.1875 = 0.123: already over the 0.1 "good" line, from one banner.

Now drag the banner taller than the block (try 300 px banner, 100 px block). The old and new positions no longer touch, so the impact region is two separate boxes, 100 + 100 = 200 px tall, and the empty gap between them doesn't count: impact 0.3125, distance 0.469, score 0.146.

Notice that the banner itself doesn't score. It's new, so it didn't move. What scores is the content it pushed.

From shifts to CLS: session windows

A page can shift many times over a long visit. Adding up every shift forever would punish pages people keep open for an hour, so CLS groups shifts into session windowsSession window (CLS)How CLS groups layout shifts: shifts less than 1 s apart join one window, up to 5 s long. A page's CLS is the total of its worst window, not of the whole visit.:

• A window starts with a shift and keeps collecting shifts that come less than 1 s after the previous one.
• A window lasts at most 5 s.
• CLS is the total of the worst window.

What doesn't count

• Shifts within 500 ms of a tap, click or key press. The user caused them, like opening an accordion. (Scrolling doesn't count as input here.) In code, these entries have hadRecentInput: true (§04).
• transform animations. Moving an element with transform doesn't change layout, so nothing "shifts". Animate transform, never top or margin (How Browsers Render §06 explains the cost side too).
• Content outside the viewport, and new content that doesn't push anything (appended at the bottom, or overlaid on top).

The usual culprits, and their fixes

.ad-slot     { min-height: 250px; }                 /* the usual ad size for this slot */
.video-embed { aspect-ratio: 16 / 9; width: 100%; } /* height follows from the width */
.cookie-bar  { position: fixed; inset: auto 0 0 0; } /* floats over the page, pushes nothing */

Ship less JavaScript: code splitting and budgets

Why JavaScript is the expensive byte

Compare 150 KB of image with 150 KB of compressed JavaScript. The image is downloaded and decoded, mostly off the main thread, and then it's done. The JavaScript is downloaded, then decompressed to several times its size, parsed, compiled and executed on the Main threadMain threadThe single browser thread that runs your JavaScript and also does style, layout and most painting. While it's busy with a long task, the page can't respond to clicks or update.. While that happens, the page can't respond: input delay (§08). On a mid-range phone this costs several times longer than on your laptop.

That's why most sites' INP and LCP problems end in the same place: too much JavaScript, too early.

Code splitting with import()

By default a BundlerBundlerA build tool (Vite/Rollup, esbuild, webpack) that follows your imports and combines your modules and libraries into a few optimized files for the browser. follows every import and packs everything into one file, the bundleBundle (front-end)The JavaScript file(s) a build tool like Vite or webpack produces for the browser. Every user downloads it and can read it with View Source or DevTools.. Code splittingCode splittingBreaking an app's JavaScript into several chunks so the browser downloads only what the current page needs, loading the rest on demand. breaks it up. The tool is the dynamic import()Dynamic import()import("./chart.js") written as a function call. It loads the module when that line runs and returns a promise of the module's exports. Bundlers turn each one into a separate chunk.:

emojiButton.addEventListener("click", async () => {
  const { openPicker } = await import("./emoji-picker.js");   // ← downloaded on first click
  openPicker(textarea);
});

In React: React.lazy and Suspense

import { lazy, Suspense, useState } from "react";

const EmojiPicker = lazy(() => import("./EmojiPicker.jsx"));   // its own chunk

export function Composer() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <textarea />
      <button onClick={() => setOpen(true)}>😀</button>
      {open && (
        <Suspense fallback={<p>Loading…</p>}>
          <EmojiPicker />
        </Suspense>
      )}
    </>
  );
}

This widget is built exactly like that. The report panel's code is a separate file in this site's source; open it and the widget reports what actually happened on the network:

Close it and open it again: the second time there's no download and no fallback, because the module is already loaded.

Measured: what splitting saved

We built a small React 19 app twice with Vite 8: a text box with an emoji-picker button. The picker includes its data, 1,670 emoji with names. Once with a normal import, once with React.lazy:

Sizes as printed by vite build. "Ready" is the time until the text box existed, in headless Chromium 153 with Slow-4G emulation and 4× CPU slowdown, median of 5.

A quarter of the main bundle moved out, and the page was usable about 160 ms sooner, for a feature many visitors never open. The remaining 69 KB is almost all React and React DOM themselves.

Where to split

• Routes. Each page of a Single-page appSingle-page app (SPA)A web app that loads one HTML page and then changes the view with JavaScript as you navigate, instead of loading a new page from the server each time. only needs its own code. Most routers support lazy routes; this is the biggest, easiest win.
• Things behind a click. Modals, editors, emoji pickers, charts, date pickers, admin panels.
• Heavy libraries used in one place. A PDF renderer, a syntax highlighter, a map.
• Not tiny components. Every chunk is another request with its own round trip; splitting a 2 KB button out costs more than it saves.

Hide the delay by starting the download when the user shows intent, before they click:

const loadPicker = () => import("./EmojiPicker.jsx");
const EmojiPicker = lazy(loadPicker);

<button onPointerEnter={loadPicker} onFocus={loadPicker} onClick={() => setOpen(true)}>😀</button>

Hovering or focusing the button starts the download; by the time the click lands, the chunk is often already there. Calling loadPicker several times is fine, because the browser loads a module once.

Keep it small: compression and budgets

Text files must be compressed on the way out. gzip or BrotliCompression (gzip, Brotli)The server shrinks text files (HTML, CSS, JS) before sending them and the browser unpacks them, announced with the Content-Encoding header. Brotli files are usually 15–20% smaller than gzip for JavaScript. are applied by your server or CDN, announced with the Content-Encoding header. Our eager bundle above: 319 KB raw, 93.6 KB with gzip (as vite build reports it), 78 KB with Brotli at its highest setting, 16% smaller than gzip.

Bundles grow one innocent npm install at a time, so make size a test that can fail. A performance budgetPerformance budgetA limit the team agrees on and checks automatically, e.g. "main JavaScript ≤ 170 KB compressed" or "LCP ≤ 2.5 s in the lab test". A build that goes over fails, like a failing test. is a number checked in CICI (continuous integration)A server that builds your code and runs its tests automatically on every push (GitHub Actions, GitLab CI, …), so mistakes are caught minutes after they're made. A flaky test there blocks everyone's merges. (the server that builds and tests every push):

npm install --save-dev size-limit @size-limit/file   # the tool, plus its plugin for measuring plain files

{
  "scripts": { "size": "size-limit" },
  "size-limit": [
    { "path": "dist/assets/index-*.js", "limit": "75 kB" }
  ]
}

Pick numbers from where you are today plus a little room, and lower them as you improve. Before adding a dependency, check what it costs compressed, and whether you need all of it; Build Tools explains tree shaking, which removes the parts you don't import, and how to read the bundle a build produced.

Resource hints and caching

The hints

Resource hintsResource hintA <link> in the HTML that tells the browser about work it will need soon — connect to a server (preconnect), download a file (preload), or fetch something for the next page (prefetch) — before it would discover it on its own. are <link> tags in the <head>. Each tells the browser something it would otherwise discover later:

(The crossorigin on the font preconnect matters: font requests use CORS mode (§07), and the browser keeps CORS and non-CORS connections apart, so the connection must be opened in the same mode the font request will use.)

A preconnectPreconnect<link rel="preconnect" href="https://other.example">: open the connection (DNS, TCP, TLS) to another server now, so the first request to it later doesn't wait for those round trips. saves the round trips of setting up a connection (three of them in our model, 450 ms on the slow phone). A preloadPreload<link rel="preload" href=… as=…>: download this file now, at high priority, because this page will need it soon. It doesn't run or apply the file; the page still has to use it. saves the discovery delay. A prefetchPrefetch (resource hint)<link rel="prefetch" href=…>: download a file at low priority when the browser is idle, because the next page will probably need it. Not the message-queue prefetch setting. helps the next page, not this one. Turn them on in our waterfall model from §02 and watch the font row:

Caching: the fastest request is the one you don't make

On a repeat visit, the browser's HTTP cacheHTTP cache (browser)The browser's store of earlier responses, reused according to Cache-Control, ETag and related headers so repeat visits load without (or with smaller) network requests. can serve files without touching the network, if the response headers allowed it. The pattern every modern build uses has two halves:

1. Hashed file names for assets. A build tool like Vite names files after a fingerprint of their content: index-3f9a1c.js. Change one character and the next build produces a new name. So an old name can be cached forever: its content will never change.
2. HTML that's always checked. index.html keeps its name, so it must not be reused blindly. Otherwise users would keep loading an old page pointing to old asset names.

Here's that policy as server code. Both versions serve a Vite dist/ folder:

package main

import (
	"log"
	"net/http"
	"strings"
)

const dist = http.Dir("dist")

// cacheHeaders decides how long browsers and CDNs may reuse each response.
func cacheHeaders(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if strings.HasPrefix(r.URL.Path, "/assets/") {
			// Vite puts a content hash in these names: a new build = a new URL.
			if isFile(dist, r.URL.Path) { // ← never cache a 404 for a year
				w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
			}
		} else {
			// HTML: reuse only after checking with the server (a cheap 304 if unchanged).
			w.Header().Set("Cache-Control", "no-cache")
		}
		next.ServeHTTP(w, r)
	})
}

func isFile(dir http.Dir, name string) bool {
	f, err := dir.Open(name) // http.Dir cleans the path, so "../" can't escape dist/
	if err != nil {
		return false
	}
	defer f.Close()
	st, err := f.Stat()
	return err == nil && !st.IsDir()
}

func main() {
	files := http.FileServer(dist) // also sends Last-Modified and answers 304s
	log.Fatal(http.ListenAndServe(":8080", cacheHeaders(files)))
}

The full story of ETag, Last-Modified, stale-while-revalidate and CDN caching is in Caching §09 and HTTP §08. A Service workerService workerA script the browser runs in the background, separate from the page, that can intercept the page's network requests — the basis of offline support and push notifications. can go further and serve the whole app offline; Browser Storage covers it.

Staff-level: RUM, attribution, bfcache and regressions

1. RUM that points at causes

A dashboard that says "INP p75: 380 ms" starts a meeting, not a fix. The web-vitals library's attribution build adds the diagnosis to each report:

import { onCLS, onINP, onLCP } from "web-vitals/attribution";

// send(name, value, details): your own helper, like §04's send(), that POSTs one beacon with navigator.sendBeacon

onLCP(({ value, attribution: a }) => send("LCP", value, {
  element: a.target,                          // CSS selector of the LCP element
  ttfb: a.timeToFirstByte, loadDelay: a.resourceLoadDelay,
  loadDuration: a.resourceLoadDuration, renderDelay: a.elementRenderDelay,   // the four parts from §05
}));

onINP(({ value, attribution: a }) => send("INP", value, {
  target: a.interactionTarget, type: a.interactionType,                       // what was clicked, "pointer" or "keyboard"
  inputDelay: a.inputDelay, processing: a.processingDuration, presentation: a.presentationDelay,  // §08
  scripts: a.longAnimationFrameEntries?.flatMap((f) => f.scripts.map((s) => s.sourceURL)),         // who ran
}));

onCLS(({ value, attribution: a }) => send("CLS", value, { element: a.largestShiftTarget }));

Field names checked against web-vitals 6.2 (the current version at the time of writing; they were the same in v4). Check the README of the version you install, since major versions sometimes rename fields.

Now the meeting has an agenda: "INP is bad on the product page, on Android, when tapping button.add-to-cart, and 70% of it is input delay caused by chat-widget.js."

2. Segment, don't average

• Per page type (product, search, checkout), not per site: a fast home page hides a slow checkout.
• Per device class (mobile and desktop at least; Chromium's navigator.deviceMemory and navigator.connection.effectiveType give rough hints). The phone segment is almost always the one failing.
• 75th percentile per segment, tracked over time, with enough samples. A p75 from 40 visits jumps around; don't react to it.
• Field data lags. CrUX is a rolling 28-day window, so a fix shipped today takes weeks to show fully there. Your own RUM shows it in a day.

3. Stop regressions before they ship

Performance usually dies by a thousand cuts: a new dependency, a second analytics tag, a bigger hero image. What holds the line:

• Byte budgets in CI (§11): cheap, deterministic, catch most regressions.
• Lab tests on key pages in CI (Lighthouse CI or WebPageTest) with a throttled phone profile, comparing medians of several runs against a threshold.
• A RUM alert on the p75 of each vital per page type, compared week over week, so what slips past CI is caught within days.
• An owner for third-party scripts. Each tag added through a tag manager runs on your main thread. Require a reason and an expiry date for every one, and measure their cost: DevTools' Network panel can block a single URL so you can compare with and without it.

4. The back/forward cache: instant navigations for free

When a user leaves a page, the browser can keep the whole page, with its JavaScript state, frozen in memory. Press Back and it's restored instantly: no network, no parsing, no rendering. That's the back/forward cache (bfcache)Back/forward cache (bfcache)A browser feature that keeps a whole page, including its running JavaScript, frozen in memory when you navigate away, so the Back button can restore it instantly.. Back and forward navigations are a large share of all navigations, so being eligible is one of the biggest wins available, and it costs nothing, as long as you don't block it.

Common blockers:

• unload event listeners. Use pagehide (or visibilitychange) instead; unload is also unreliable on mobile.
• Cache-Control: no-store on the HTML, which historically made Chromium skip the bfcache (newer versions relax this in some cases).
• Open connections such as an active WebSocket or IndexedDB transaction when the user navigates away; close them on pagehide and reopen on pageshow.

window.addEventListener("pageshow", (event) => {
  if (event.persisted) refreshPrices();   // ← true when restored from the bfcache: data may be stale
});

Chrome DevTools → Application → Back/forward cache has a "Test" button that tells you whether a page is eligible and, if not, exactly why.

5. Single-page apps: what the metrics see

Core Web Vitals are measured per page load. In a Single-page appSingle-page app (SPA)A web app that loads one HTML page and then changes the view with JavaScript as you navigate, instead of loading a new page from the server each time., a route change isn't a page load, so:

• LCP only measures the first page the user landed on. Later routes have no LCP.
• INP and CLS keep accumulating over the whole session across route changes, and are reported against the URL the visit started on.

Chromium has been experimenting with a "soft navigations" API that would measure route changes as navigations; until that is standard, measure route changes yourself (time from click to the new view's main content) with performance.mark() and performance.measure(), and send them with your RUM.

Pitfalls gallery

<img src="/hero.avif" loading="lazy" alt="…">

<img src="/hero.avif" width="1200" height="800" fetchpriority="high" alt="…">

<link rel="preload" href="/fonts/brand.woff2" as="font" type="font/woff2">  <!-- downloads twice -->

window.addEventListener("unload", saveDraft);   // blocks the back/forward cache in many browsers

Check yourself

Commit to an answer before you click. Each explanation points back to the section that covers it.

<img src="/hero-2400.jpg" loading="lazy" alt="Kayak on a lake">

<link rel="preload" href="/fonts/brand.woff2" as="font" type="font/woff2">

const Editor = lazy(() => import("./Editor.jsx"));

Cheat sheet