completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

Measuring soft navigations

Core Web Vitals see one page per visit. Measure each route change in a single-page app: Chrome's Soft Navigations API, web-vitals, CrUX's new metrics, and your own marks.

By the end, you can
  • 01
    Tell when Chrome sees a new pageName the three things a route change needs before Chrome reports it as a soft navigation, and spot the ones it misses.
  • 02
    Report each page on its ownRead soft-navigation entries, give each route its own LCP, INP and CLS with web-vitals, and find them in CrUX.
  • 03
    Time route changes yourselfMark each route change with User Timing, so every browser and every route is measured, and compare single-page and multi-page apps.

One report for a whole visit

Ravi's tea shop is a single-page app. The browser loads one page, shop.html, once. After that, his JavaScript swaps one screen for another. Each screen is a route. You made his route changes fast in lesson 34.1.

Asha visits. She lands on the list of teas. She taps Mint tea and picks the 50 g size. She opens the reviews. Then she goes back to the list and taps Green tea. That's six screens.

Ravi sends his Core Web Vitals to his server with the web-vitals library, as in lesson 12.1. That evening, he looks for Asha's visit. He finds one row:

Ravi's report for Asha's visitPop out in the code editor (opens in a new tab)JavaScript
// Ravi's web-vitals report for Asha's visit, sent the usual way.// Six screens, but one report.const report = { page: "shop.html", LCP: 1052, INP: 208, CLS: 0.07 }; console.log(`One page: ${report.page}`);console.log(`LCP ${report.LCP} ms, INP ${report.INP} ms, CLS ${report.CLS}`);
  • Lines 1 and 2 are comments. This is the report web-vitals sends the usual way.
  • Line 3 holds the recorded numbers. CLS was 0.0736, shown here to two places.
  • Line 5 prints One page: shop.html. Line 6 prints LCP 1052 ms, INP 208 ms, CLS 0.07.

Six screens, one report. Somewhere in the visit, a tap took 208 ms. Something on some screen jumped. Which screen was it? The report can't say. It files everything under the first address. Here is the visit, frame by frame:

Asha's visit to Ravi's single-page app in six real frames from Chrome: the list, Mint tea, Mint tea at 50 g, the reviews, the list again and Green tea. Under all six, one bar: the usual report sees one page, shop.html, with LCP 1,052 ms, INP 208 ms and CLS 0.07.Asha landsRavi's list of teas, Our teas, with Mint tea's photo, name and price at the top.the listtaps Mint teaMint tea's page: its photo, name, price for 100 g, buttons for 50 g and 100 g, a Reviews button and a link back to the teas.Mint teataps 50 gThe same page with the price changed to £2.25 for 50 g.50 gtaps ReviewsA Reviews view with three short reviews and a link back to the teas.Reviewsback to teasThe list of teas again.the listtaps Green teaGreen tea's page, with a green Back in stock this week note above its photo.Green teaWhat Core Web Vitals sees: one page, shop.htmlLCP 1,052 ms · INP 208 ms · CLS 0.07
Real frames from Chrome. Six screens, but the usual report sees one page, with one LCP, one INP and one CLS.
Real-life analogyA visitors' book at the front door

A museum asks visitors to sign a book at the front door. Inside, you walk through ten rooms. One room is packed and slow. But the book only knows you came in. If the museum wants to know which room was slow, someone has to write in each room too.

In real life: Signing in at the front door
In JavaScript: A hard navigation: a new document from the server
In real life: Walking from room to room
In JavaScript: A route change inside the same document
In real life: The whole day filed under the entrance
In JavaScript: Every metric filed under the first address
In real life: A guard in each room with a notebook
In JavaScript: Soft navigations: one report per page
The main idea

A route change is a new page to your visitor, but not to the usual metrics. Chrome now spots it as a soft navigation, if a tap changed the address and painted new content. web-vitals can then report each page on its own. CrUX publishes the same idea for the whole web. Your own marks can time every route, in every browser.

Those are this lesson's ways to see each route. For how single-page apps differ from sites that load a new page each time, see Single-page vs multi-page apps.

How the course recorded it

  • Ravi's app: lesson 34.1's app, with the tea page's grey frame drawn at once. This version adds a size picker, a Reviews button and a stock note that arrives late.
  • Asha's network and computer: the course's server played Fast 4G, so each answer waited 165 ms. Building a tea's data took 250 ms more. Chrome 157 ran with the CPU 4 times slower.
  • Real taps: mouse clicks, sent the way DevTools sends them. Chrome passes these straight to the page.
  • What was read: web-vitals 6.2.3, both the usual way and per page, and every soft-navigation entry. The course made 3 visits and quotes the middle one.

Why route changes are invisible to the metrics

The metrics were built around documents. A hard navigation loads a new document from the server. Each one starts every clock again. A soft navigation changes the screen and the address with JavaScript, but keeps the same document.

Asha's visit had one hard navigation. Everything after it happened inside it. Three things follow from that:

  • One navigation entry. Navigation Timing writes one entry per document, as lesson 5.1 showed.
  • LCP stops at the first tap. Chrome stops looking for the largest paint at the first tap, click, key press or scroll. Lesson 17.1 explained why.
  • INP and CLS cover the page's whole life. Every tap and every jump, on any screen, goes into one number.
What Chrome kept for the whole visitPop out in the code editor (opens in a new tab)JavaScript
// What Chrome kept for the whole visit, read at the end. In ms.const navigationEntries = 1;const lastLcpEntry = 1052;const firstTap = 2676.8; console.log(`${navigationEntries} navigation entry for six screens`);console.log(lastLcpEntry < firstTap ? "LCP stopped at the first tap" : "LCP kept going");
  • Line 2 is how many navigation entries the page had at the end.
  • Line 3 is the last LCP entry, a photo in the list. Line 4 is Asha's first tap, on Mint tea.
  • Line 6 prints 1 navigation entry for six screens. Line 7 prints LCP stopped at the first tap.

web.dev's guide to single-page apps says the same. Metric values were not reset, and each was tied to "the URL the user navigated to that initiated the page load."

Why it matters: the usual report blames the landing page for problems on other screens. And it never times a route change at all.

What Chrome counts as a soft navigation

From Chrome 151, the browser spots route changes by itself. Lesson 30.4 used this to split CLS by page. Now look at the rule closely.

Real-life analogyAn order counts when the food reaches the table

A waiter marks an order as served only when three things happened. A customer asked for it. It was written on a ticket. And food reached the table. Bread that nobody ordered doesn't count. Neither does cutlery on its own.

In real life: A customer asks for a dish
In JavaScript: An interaction: a tap, click or key press
In real life: The order on the ticket
In JavaScript: A new address in the address bar
In real life: Food on the table
In JavaScript: New text or an image painted
In real life: Cutlery, brought at once
In JavaScript: Ravi's grey frame: not content

Chrome needs all three, in the same way:

  1. An interaction: a tap, a click or a key press. The browser's own Back button counts too.
  2. A new address: from pushState, replaceState, the Navigation API, or a new #fragment.
  3. New content: text or an image that the interaction put on the page, painted on screen.

"Put on the page by the interaction" is the clever part. Chrome follows the tap's work through timers, fetch() and await. So a page drawn when its data arrives, 400 ms later, still belongs to the tap. Here is what Chrome reported for Asha's visit:

Chrome's soft-navigation entriesPop out in the code editor (opens in a new tab)JavaScript
// Chrome's soft-navigation entries from Asha's visit, names shortened.// startTime and duration are in ms. duration is the first contentful paint.const entries = [  { name: "?tea=mint-tea", navigationType: "push", startTime: 2676.8, duration: 435.2 },  { name: "?tea=mint-tea&size=50", navigationType: "replace", startTime: 5214, duration: 10 },  { name: "shop.html", navigationType: "push", startTime: 8741.6, duration: 174.4 },  { name: "?tea=green-tea", navigationType: "push", startTime: 11058.8, duration: 425.2 },];for (const entry of entries) console.log(`${entry.name}, ${entry.navigationType}: FCP ${entry.duration} ms`);
  • Lines 4 to 7 are the four entries Chrome made, with their addresses shortened.
  • Line 9 prints one line each. The first is ?tea=mint-tea, push: FCP 435.2 ms. The second is ?tea=mint-tea&size=50, replace: FCP 10 ms.

Asha tapped five times, but Chrome made four entries. Two taps are worth a closer look:

  • Reviews made no entry. It swapped the whole view for the reviews. To Asha, that was a new page. But the address stayed the same, so to Chrome it wasn't.
  • 50 g made one. It wrote &size=50 into the address with replaceState, which swaps the current history entry instead of adding one. It also painted a new price. To Asha, that was the same page.

The spec's authors expect this. Their explainer leaves the rest of the filtering "to the developer": the address and the navigationType are there for you to group by. Why it matters: Chrome's count can miss a whole view, and it can count a small change as a page.

The entry waits for content

Look at Mint tea again. Ravi's app draws the tea page's grey frame in the tap, as in lesson 34.1. The address changes at once too. But grey boxes aren't text or images.

The tap on Mint tea, step by stepPop out in the code editor (opens in a new tab)JavaScript
// Asha taps Mint tea. In ms after the tap:const addressChanged = 2.5;const greyFrameDrawn = 5.4;const teaPainted = 435.2; // the soft navigation's first contentful paint console.log(`Grey frame at ${greyFrameDrawn} ms: not content, so no entry yet.`);console.log(`No entry for ${(teaPainted - addressChanged).toFixed(1)} ms after the address changed.`);
  • Lines 2 to 4 are recorded times, in ms after the tap.
  • Line 6 prints Grey frame at 5.4 ms: not content, so no entry yet.
  • Line 7 prints No entry for 432.7 ms after the address changed.
Asha taps Mint tea. Three real frames: the list at the tap; the grey frame at 5.4 ms, with the new address already in place; the tea's text and photo at 435.2 ms. Under them, a bar from 2.5 ms to 435.2 ms: the address had changed, but there was no soft-navigation entry yet.the tap, 0 msRavi's list, at the moment Asha taps Mint tea.shop.htmlgrey frame, 5.4 msThe tea page's grey frame: a grey box where the photo goes and two grey bars. No text, no image.?tea=mint-teatea painted, 435.2 msMint tea's page, with its photo, name and price.?tea=mint-teathe address had changed, but no entry yet0 msthe entry: FCP 435.2 ms
Real frames from Chrome. The address changed in the tap, but the soft navigation only began when the tea's text and photo were painted.

Until the tea was painted, there was no soft navigation. If Asha had given up during the grey frame, Chrome would have made no entry at all. Why it matters: the slowest route changes, the ones visitors leave, can be missing from your data.

Inside Chrome

Chrome's own code makes the same checks, in soft_navigation_heuristics.cc:

  • Lines 422 to 425 check for the interaction, the new address and a change to the page.
  • Lines 428 to 431 check the painted area. Lines 739 to 749 set it at 0.01% of the screen, and at least one pixel. So one new price is enough.
  • Lines 317 to 319 skip an address that didn't really change. Lines 211 to 214 skip iframes.
  • Lines 443 to 456 give the page its new navigationId at that paint. Entries from before it, like a layout shift during the grey frame, keep the old one.

One more rule lives in soft_navigation_context.cc, lines 95 to 99. Once the visitor taps again or scrolls, later paints stop counting for that page's LCP. Tick what a route change did, and see what Chrome decides:

Playground: will Chrome count it?
The rule, in plain JavaScriptJavaScript
// Chrome's three checks, in plain words.
function isSoftNavigation({ byUser, newAddress, newContent }) {
  return byUser && newAddress && newContent;
}
Chrome's answercounted

Chrome reports a soft navigation.

Asha's taps like this oneMint tea, 50 g, Back to the teas, Green tea
Try it yourself
All three: a new page

Chrome gives it a soft-navigation entry and a new navigationId, once the new content is painted.

Tick what a route change did. The rule comes from Chrome's own code. The list shows which of Asha's recorded taps did the same.

Each page's own Core Web Vitals

Each soft navigation gets a soft-navigation entry. You read it with a PerformanceObserver, like any other entry:

Watch soft navigationsJavaScript
new PerformanceObserver((list) => {  for (const entry of list.getEntries()) {    const largest = entry.getLargestInteractionContentfulPaint();    const lcp = largest.largestContentfulPaint.renderTime - entry.startTime;    console.log(entry.name, entry.navigationType, entry.navigationId);    console.log(`FCP ${entry.duration} ms, LCP so far ${lcp} ms`);  }}).observe({ type: "soft-navigation", buffered: true });
  • Line 3 asks for the largest new paint so far. It's an interaction contentful paint: an entry Chrome makes for any interaction's new content, page or not. Inside it is an LCP entry.
  • Line 4 subtracts the entry's startTime, the moment of the tap. Every time is counted from the first load, so a soft navigation's LCP needs this subtraction.
  • Line 5 prints the new address, the navigationType and the navigationId, a number for this page. Every other entry, like a layout shift or a tap, carries the navigationId of the page it happened on.
  • Line 6 prints the entry's duration: its first contentful paint, counted from the tap.

In Asha's visit, the numbers were 7898 for the first load, then 7905, 7912, 7919 and 7926. The spec starts them at a random number and steps by an amount the browser picks. So match them, but don't count with them.

web-vitals does all this for you. Ask for each metric twice:

Both reports from web-vitalsJavaScript
import { onCLS, onINP, onLCP } from "web-vitals"; onLCP(sendAsUsual);onINP(sendAsUsual);onCLS(sendAsUsual);onLCP(sendPerPage, { reportSoftNavs: true });onINP(sendPerPage, { reportSoftNavs: true });onCLS(sendPerPage, { reportSoftNavs: true });
  • Lines 3 to 5 send the usual reports: one per metric for the whole visit.
  • Lines 6 to 8 pass reportSoftNavs: true. Now each page gets its own report. Its navigationURL names the page, and its navigationType is soft-navigation.

On a soft navigation, each metric changes like this. Read each row across:

Each metric, as usual and on a soft navigation
MetricAs usualOn a soft navigation
TTFBThe time to the page's first byte.Always 0. A route change has no first byte of its own.
FCPThe first text or image painted.The first new text or image the tap painted, counted from the tap.
LCPThe largest element painted before the first tap, key press or scroll.The largest new element the tap painted. What stayed on screen doesn't count.
INPThe slowest tap over the page's whole life.Starts again. The tap that started the route change usually counts for the page before.
CLSThe worst burst of layout shifts over the page's whole life.Starts again, for this page alone.

So where did Asha's two problems land?

Where the slow tap and the jump were filedPop out in the code editor (opens in a new tab)JavaScript
// Where web-vitals filed the slow tap and the layout shift.const asUsual = { INP: "shop.html", CLS: "shop.html" };const perPage = { INP: "?tea=mint-tea&size=50", CLS: "?tea=green-tea" }; console.log(`INP 208 ms: ${asUsual.INP} as usual, ${perPage.INP} per page`);console.log(`CLS 0.07: ${asUsual.CLS} as usual, ${perPage.CLS} per page`);
  • Line 2 is the usual report. Line 3 is the report per page.
  • Line 5 prints INP 208 ms: shop.html as usual, ?tea=mint-tea&size=50 per page.
  • Line 6 prints CLS 0.07: shop.html as usual, ?tea=green-tea per page.
Asha's visit filed two ways. As usual: one report for shop.html, with LCP 1,052 ms, INP 208 ms and CLS 0.07. With reportSoftNavs: five reports, one per page. shop.html: LCP 1,052 ms. ?tea=mint-tea: LCP 435.2 ms. ?tea=mint-tea&size=50: INP 208 ms. shop.html: LCP 174.4 ms. ?tea=green-tea: CLS 0.07.As usual: one reportshop.htmlLCP 1,052 msINP 208 msCLS 0.07With reportSoftNavs: one report per pageshop.html: LCP 1,052 ms?tea=mint-tea: LCP 435.2 ms?tea=mint-tea&size=50: INP 208 msshop.html: LCP 174.4 ms?tea=green-tea: CLS 0.07
The same visit, filed two ways. Per page, the slow Reviews tap lands on the 50 g page, and the late stock note's shift on Green tea's.

Per page, both problems landed on the right screen. The jump was Green tea's late stock note. The slow tap was Reviews. It counted for the 50 g page, the page Chrome thought Asha was on. Why it matters: group &size=50 under its tea before you compare pages.

Pick a step of the visit to see its numbers:

Playground: each page of Asha's visit
Mint teaRecorded
Addressshop.html?tea=mint-tea
Soft-navigation entrypush, at 2,676.8 ms
TTFB, per page0 ms
FCP, per page435.2 ms
LCP, per page435.2 ms
INP, per page8 ms
CLS, per page0
Ravi's own measure431.2 ms
Try it yourself
Mint tea

A soft navigation. Its clock starts at the tap, so TTFB is 0 and FCP and LCP count from the tap.

Recorded in Chrome 157, CPU 4 times slower, Fast 4G, with web-vitals 6.2.3: the middle of 3 visits. As usual, the whole visit was one report: TTFB 166.2 ms, FCP 224 ms, LCP 1,052 ms, INP 208 ms, CLS 0.0736. On a page whose taps were all too quick to time, web-vitals reports a stand-in: 0 ms on the first page, 8 ms on a soft navigation.

Soft navigation metrics in CrUX

CrUX is Chrome's field data from real visitors, as lesson 10.1 showed. It now publishes three Core Web Vitals with soft navigations too:

  • experimental_largest_contentful_paint_with_softnavs
  • experimental_interaction_to_next_paint_with_softnavs
  • experimental_cumulative_layout_shift_with_softnavs

Each one counts hard and soft navigations together. The first load's INP and CLS end at the first soft navigation. In the CrUX API, a route change is filed under its own address. The API also has FCP and navigation types with soft navigations.

Real-life analogyA trial column on a school report

A school tries a new way of grading. For a while, report cards show both columns: the official grade and the trial one. Parents can compare them. Later, the trial becomes the official grade.

In real life: The official grade
In JavaScript: The stable Core Web Vitals
In real life: The trial column next to it
In JavaScript: The experimental_*_with_softnavs metrics
In real life: Next year, the trial becomes official
In JavaScript: Search Console will switch once they graduate

The stable Core Web Vitals stay as they are for now. Chrome plans to make these the main ones, and Search Console will then switch to them. You can ask the CrUX API for both at once:

LCP from the CrUX API, both waysJavaScript
const response = await fetch(`https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${API_KEY}`, {  method: "POST",  headers: { "Content-Type": "application/json" },  body: JSON.stringify({    origin: "https://www.youtube.com",    metrics: ["largest_contentful_paint", "experimental_largest_contentful_paint_with_softnavs"],  }),});const { record } = await response.json();console.log(record.metrics.experimental_largest_contentful_paint_with_softnavs.percentiles.p75);
  • Lines 1 to 3 send a request to the CrUX API, with your API key, as JSON.
  • Line 5 asks about one origin: a site's scheme and host, like https://www.youtube.com.
  • Line 6 asks for the usual LCP and the one with soft navigations.
  • Line 10 prints the 75th percentile with soft navigations: the time that 75% of page views were at or under.

BigQuery is Google's database service, and CrUX publishes a table there every month. Its summary table has these metrics in columns that end in _sn. The course ran a query like this one on the newest month of CrUX data, with the INP and CLS columns too:

Both LCPs from BigQuerySQL
SELECT origin, p75_lcp, p75_lcp_sn, fast_lcp, fast_lcp_snFROM `chrome-ux-report.materialized.metrics_summary`WHERE date = (SELECT MAX(date) FROM `chrome-ux-report.materialized.metrics_summary`)  AND origin IN ("https://www.youtube.com", "https://github.com", "https://en.wikipedia.org", "https://completefrontend.com")

Line 1 picks the usual p75 and the one with soft navigations, and the share of good LCPs both ways. Line 3 picks the newest month, and line 4 picks four origins. Good LCP is the share of page views at or under 2.5 seconds. Read each row across: as usual, then with soft navigations.

Four origins in one month of CrUX
OriginLCP, p75Good LCPINP, p75CLS, p75
www.youtube.com4,600 ms, then 2,400 ms.31.2%, then 75.1%.225 ms, then 150 ms.0.35, then 0.15.
github.com1,800 ms, then 1,500 ms.86.8%, then 90.3%.75 ms, both times.0, both times.
en.wikipedia.org900 ms, then 800 ms.95.9%, then 96.4%.75 ms, both times.0, both times.
completefrontend.com1,100 ms, both times.93.9%, then 94.1%.75 ms, both times.0, both times.

YouTube's LCP almost halved. Its share of good LCPs more than doubled. Wikipedia barely moved, and this site's p75 didn't move. The web.dev blog post explains the pattern. Big changes come from single-page apps whose visitors make many route changes. About 70% of origins have almost no soft navigations. Only 7 to 11% use them for more than half their page views. Among the top 1,000 sites, it's 35% on Android and 42% on desktop.

Why it matters: if your site is a single-page app, look at the soft navigation metrics before you trust its Core Web Vitals.

Measuring route changes yourself

The API has gaps. Only Chromium browsers have it. It never saw the Reviews view. And it can't know what your router knows: which route, and which data. So time route changes yourself too, with User Timing: your own named marks on the page's clock, from lesson 11.6.

Real-life analogyYour own stopwatch next to the race clock

At a race, the official clock times every runner. You can also carry your own stopwatch. Press start at the gun, not when you remember. Then your time matches the official one closely, and it works on practice runs too.

In real life: The race's official clock
In JavaScript: Chrome's soft-navigation entries
In real life: Your own stopwatch
In JavaScript: performance.mark() and performance.measure()
In real life: Pressing start at the starting gun
In JavaScript: Starting the mark at event.timeStamp
In real life: A practice run with no official clock
In JavaScript: A browser or route Chrome doesn't measure

Ravi's router times each route change itself. Here is the part that does it:

Ravi's router times each route changeJavaScript
const afterNextPaint = () => new Promise((done) => requestAnimationFrame(() => setTimeout(done)));document.addEventListener("click", async (event) => {  const link = event.target.closest("a[data-route]");  if (!link) return;  event.preventDefault();  performance.mark("route-start", { startTime: event.timeStamp });  history.pushState(null, "", link.href);  await route();  await afterNextPaint();  performance.measure("route", { start: "route-start", detail: location.search || "/" });});
  • Line 1 makes afterNextPaint. It waits for the next frame, then for one more task, just after that frame has been drawn.
  • Line 6 makes a mark. Its startTime is the click's own timeStamp, so the clock starts at the tap, as Chrome's does.
  • Lines 7 and 8 change the address and draw the route.
  • Lines 9 and 10 wait for the frame, then measure from the mark. The detail keeps which route it was.

How close did Ravi's clock get to Chrome's?

Ravi's measure next to Chrome's LCPPop out in the code editor (opens in a new tab)JavaScript
// Each route change, in ms after the tap: Ravi's measure and Chrome's LCP.const routes = [  { route: "Mint tea", own: 431.2, chrome: 435.2 },  { route: "The list", own: 173.1, chrome: 174.4 },];for (const { route, own, chrome } of routes)  console.log(`${route}: ${own} and ${chrome}, ${(chrome - own).toFixed(1)} ms apart`);
  • Lines 3 and 4 are two route changes from the visit, in ms after the tap.
  • Line 7 prints Mint tea: 431.2 and 435.2, 4.0 ms apart and The list: 173.1 and 174.4, 1.3 ms apart.

Ravi's clock stopped a little early. Chrome's LCP is the moment the frame reached the screen. Ravi's timer runs once the frame has left the page's main thread. Why it matters: a few milliseconds apart, your own clock works in every browser, and for every route.

A few habits make your own clock useful:

  • Start at the event's timeStamp, not when your code gets round to it.
  • Report the route's name, like tea-page, not every full address. Then 50 g and 100 g land together.
  • In Firefox and Safari, the Navigation API's navigate event from lesson 34.1 is a good place to start the clock.
  • Send it with the rest of your field data, as in lesson 12.4.

Try it in your own browser. The button swaps the box's content without changing the address, like Ravi's Reviews button:

Playground: your own Reviews tap
What the lab doesJavaScript
// What the lab does when you tap, shortened.button.addEventListener("click", async (event) => {  performance.mark("lab-start", { startTime: event.timeStamp });  showReviews(); // swaps the box's content; the address stays the same  await afterNextPaint();  performance.measure("lab-reviews", "lab-start");});new PerformanceObserver(readPaint).observe({ type: "interaction-contentful-paint" });
Mint tea, a demothe tea
Mint tea

£4.50 for 100 g. Cool peppermint leaves.

Your own measureTap Show the reviews.
Chrome's interaction contentful paintTap Show the reviews.
Soft-navigation entriesTap Show the reviews.
Try it yourself
New content, same address

The button swaps the box below for three reviews. The page's address doesn't change, like Ravi's Reviews button.

Live, in your own browser. Your measure runs from the click's timeStamp to just after the next frame. It changes from tap to tap.

Line 3 of the lab's code starts the clock at the tap. Line 6 stops it after the next frame. In Chrome, watch the last two rows: a paint, but no soft navigation.

Single-page and multi-page apps, side by side

So is a single-page app faster? Ravi built a multi-page twin to find out. It has the same addresses, under /mpa/. But each one is a whole new page from his server, with the tea's data already in the HTML. Asha made the same visit on both: the list, Mint tea, the list again and Green tea.

Each page view's LCP, both waysPop out in the code editor (opens in a new tab)JavaScript
// The LCP of each page view, in ms. The middle of 3 visits each.const singlePage = { firstVisit: 1052, mintTea: 435.2, listAgain: 174.4 };const multiPage = { firstVisit: 764, mintTea: 460, listAgain: 200 }; for (const view of Object.keys(singlePage))  console.log(`${view}: ${singlePage[view]} single-page, ${multiPage[view]} multi-page`);
  • Line 2 is the single-page app: the first load, then two route changes. Line 3 is the multi-page twin.
  • Lines 5 and 6 print one line per page view. The first is firstVisit: 1052 single-page, 764 multi-page.
The LCP of each page view, drawn to scale, in Ravi's single-page app and its multi-page twin. First visit: 1,052 ms single-page, 764 ms multi-page. Mint tea: 435.2 ms single-page, 460 ms multi-page. The list again: 174.4 ms single-page, 200 ms multi-page. Green tea: 425.2 ms single-page, 456 ms multi-page.First visit1,052 ms764 msMint tea435.2 ms460 msThe list again174.4 ms200 msGreen tea425.2 ms456 mssingle-page appmulti-page app
The LCP of each page view, to scale, the middle of 3 visits each. The single-page app's first visit was slower. Its route changes were a little faster.

The first visit was slower in the single-page app. Its app.js had to arrive, then fetch the list, before the list was drawn. The route changes were a little faster. Each tea page waited 250 ms for Ravi's server in both versions, so neither could skip that.

The clocks differ a little, too. A soft navigation counts from the tap. A hard one counts from when the new page's navigation started, just after the click. And the twin's Mint tea page had a TTFB of 418.1 ms, while the soft navigation reported 0.

Real-life analogyA market stall, set up once

A market trader spends the morning setting up the stall. After that, serving each customer is quick. If an inspector timed only the setup, the stall would look slow all day.

In real life: Setting up the stall in the morning
In JavaScript: The single-page app's first load
In real life: Serving each customer from the stall
In JavaScript: A route change: only the data travels
In real life: A shop that opens a new counter for each customer
In JavaScript: A multi-page app: each page from the server
In real life: Counting only the morning setup
In JavaScript: Core Web Vitals without soft navigations

The field shows the same thing. In the web.dev blog post, origins with 75 to 100% soft navigations went from 26% to 87% good LCP on Android, once soft navigations were counted. The authors add: "This isn't because SPAs are faster than multi-page websites (MPAs) overall, but because follow-up clicks are faster on any site." INP got better too, but single-page apps still trail multi-page sites there. CLS caught up on desktop, and nearly on Android.

Why it matters: compare like with like. First loads with first loads, and route changes with the next page loads.

Will Chrome count it?

Each change below happens in a single-page app. Sort it by what Chrome makes of it:

Will Chrome count it?
  • A tap on a product pushes /shop/mint-tea and draws its page
  • A click on Sort by price writes ?sort=price with replaceState and redraws the list
  • When the page loads, a timer sends the visitor on to /account
  • A slideshow moves to the next photo by itself every 5 seconds and writes #slide-2
  • A Reviews tab swaps the whole view, but the address stays /shop/mint-tea
  • On the home page, a tap on the logo pushes the home page's own address again
  • A tap pushes /shop/oolong, but the visitor leaves while only grey boxes are on screen
  • A tap pushes /map/kerala, and the new view is drawn only on a canvas
Try it yourself
0 of 8 correct

Sort each change by what Chrome makes of it.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

Common mix-ups

  • "A route change is a new page to Core Web Vitals." No. The usual report sees one page per document, under the first address.
  • "Every pushState is a soft navigation." No. Chrome also needs a tap, click or key press, and new content painted by it. And replaceState counts too.
  • "If the whole view changes, Chrome counts it." No. Ravi's Reviews view changed everything but the address, and made no soft navigation.
  • "The grey frame starts the soft navigation." No. Grey boxes aren't content. The entry waited for the tea's text and photo.
  • "A soft navigation's TTFB is its data request's time." No. web-vitals reports 0.
  • "The new CrUX metrics change my Core Web Vitals today." No. They are experimental, next to the stable ones.

Practice exercises

Answer first, then use the hints.

Exercise 1 · Warm-upA soft navigation's LCP

Green tea's largest new paint came at 11,484 ms on the page's clock. What does this print?

Starter codePop out in the code editor (opens in a new tab)JavaScript
// Green tea's soft navigation, read at the end of Asha's visit.
const softNavigation = { startTime: 11058.8 };
const largest = { renderTime: 11484 };

console.log(`Green tea's LCP: ${(largest.renderTime - softNavigation.startTime).toFixed(1)} ms`);

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upBen's visit

    Ben's visit had four changes. How many would Chrome count? What does this print?

    Starter codePop out in the code editor (opens in a new tab)JavaScript
    // Four things that happened in Ben's visit to another shop.
    const changes = [
      { name: "Open a product", byUser: true, newAddress: true, newContent: true },
      { name: "Open the filters", byUser: true, newAddress: false, newContent: true },
      { name: "A timer shows the next offer", byUser: false, newAddress: true, newContent: true },
      { name: "Open the basket", byUser: true, newAddress: true, newContent: true },
    ];
    const counted = changes.filter((change) => change.byUser && change.newAddress && change.newContent);
    console.log(`${counted.length} soft navigations`);

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeRavi's clock on Green tea

      In the playground with each page of Asha's visit, what did Ravi's own measure say for Green tea, in ms?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeA clock that starts late

        This router's clock misses the first 60 ms of every route change. Fix the mark. What do you pass to it?

        Starter codeJavaScript
        document.addEventListener("click", async (event) => {
          const link = event.target.closest("a[data-route]");
          if (!link) return;
          event.preventDefault();
          saveScrollPosition(); // slow: 60 ms
          performance.mark("route-start");
          history.pushState(null, "", link.href);
          await route();
          performance.measure("route", "route-start");
        });

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeRavi's app in the Console

          Open this copy of Ravi's app in Chrome. Tap Mint tea, then Reviews. Then run performance.getEntriesByType("soft-navigation").length in DevTools' Console. What does it print?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeFCP from CrUX

            Ravi wants FCP with soft navigations from the CrUX API. Which metric name does he put in the request?

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, ask which page Chrome thinks the visitor is on, and when that page began.

              The soft navigations quiz · 7 questionsScore: first tries count
              1. Question 1 of 7What does the first line of the opening example print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // Ravi's web-vitals report for Asha's visit, sent the usual way.
                // Six screens, but one report.
                const report = { page: "shop.html", LCP: 1052, INP: 208, CLS: 0.07 };
                
                console.log(`One page: ${report.page}`);
                console.log(`LCP ${report.LCP} ms, INP ${report.INP} ms, CLS ${report.CLS}`);

                Choose an answer to see the explanation.

              2. Question 2 of 7Which three things must happen before Chrome reports a soft navigation?

                Choose an answer to see the explanation.

              3. Question 3 of 7Ravi's Reviews button swaps the whole view but keeps the address. What does Chrome report for it?

                Choose an answer to see the explanation.

              4. Question 4 of 7Asha taps Mint tea and a grey frame appears at once. When does Chrome make the soft-navigation entry?

                Choose an answer to see the explanation.

              5. Question 5 of 7What TTFB does web-vitals report for a soft navigation?

                Choose an answer to see the explanation.

              6. Question 6 of 7With reportSoftNavs, which page did the slow Reviews tap count towards?

                Choose an answer to see the explanation.

              7. Question 7 of 7In CrUX, what happened to YouTube's LCP when soft navigations were included?

                Choose an answer to see the explanation.

              Key takeaways

              • The usual Core Web Vitals see one page per document. Route changes are invisible, and everything is filed under the first address.
              • From Chrome 151, a soft navigation needs a tap, click or key press, a new address, and new text or an image painted by it.
              • The entry waits for content. It misses views with no new address, and counts small changes that write one.
              • With reportSoftNavs, web-vitals gives each page TTFB 0, FCP and LCP from the tap, and its own INP and CLS.
              • CrUX publishes experimental_*_with_softnavs metrics next to the stable ones.
              • Time route changes yourself too, from the event's timeStamp. It works in every browser and for every route.

              Remember the one-liner.
              A route change is a page to your visitor; measure it like one.

              Looking back at Instant navigations

              This was the last lesson of Stage 10. You made the next page appear at once in five ways. The back/forward cache restores a page you left. Speculation Rules prefetch or prerender the next one. Prefetching strategies guess it from the pointer, the screen or your data. Fast route changes load a route early and draw it at once. And now you can measure each route change, so you know the others worked.

              Sources

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

              Coming next: Rendering strategies compared, in Architecture and frameworks. The same page, built five ways, from client rendering to islands. You'll see how each one moves TTFB, LCP and INP.

              CompleteFrontend Clear concepts. Working examples.