Budgeting Soft-Navigation INP in SPAs

In a single-page application the browser loads the shell once and then swaps views in JavaScript, so the interactions that matter most to users — tapping a nav item, opening a detail drawer, filtering a list — happen after the one hard navigation your synthetic tools measure. This page is part of the Single-Page App Performance Budgets reference, and it shows how to set and enforce an Interaction to Next Paint (INP) budget for each client-side route change, not just the cold load. If your budget is a single INP ceiling captured on one Lighthouse run against the landing route, you are grading the least representative moment of the session.

The fix is to treat every soft navigation as its own budgeted unit: attribute each interaction to the route it occurred on, aggregate INP at the 75th percentile per route and device class, and gate a scripted CI walk that reproduces the real click paths. Below is the entry type that makes this possible, a concrete per-route budget table, the instrumentation, and a copy-paste CI flow.

Why a Single Lighthouse Run Misses Soft-Navigation INP

A default Lighthouse mobile audit loads the entry URL, drives a scripted set of interactions during a short trace window, and reports one INP figure tied to that initial document. The moment your router intercepts a link click and re-renders without a full document load, Lighthouse's lab pass is already over. Meanwhile the user is three routes deep, mounting heavier components, hydrating lists, and firing the long tasks that actually inflate INP. Because the URL in the address bar changed without a navigation event, your beacon code — if it keyed metrics on the initial navigationStart — files every one of those slow interactions under the landing route. Your dashboards then show a healthy home page and hide a 480 ms INP on the search results view.

Soft navigations also reset the mental model users bring to a page. When someone clicks into a product detail view they expect a fresh, responsive surface; an interaction that lags 350 ms on mid-range mobile over Fast 3G reads as a broken app, even though the "page" (the document) never reloaded. Budgeting per route restores the accountability that per-metric ceilings give you elsewhere in Core Web Vitals Budget Allocation: each route earns its own ceiling and its own regression alarm.

The Soft-Navigation PerformanceObserver Entry Type

Chromium exposes a soft-navigation heuristic behind the soft-navigation performance entry type. When the engine detects that a user interaction led to a DOM change and a URL update without a hard navigation, it emits a soft-navigation entry carrying a navigationId, the name (the new URL), and a startTime. Crucially, subsequent event and interaction timing entries are then attributed to that navigationId, which is exactly the join key you need to bucket INP per route. You observe both streams and correlate them.

// soft-nav-observer.js — attribute interactions to the route they happened on
const routeByNavId = new Map();
let currentNavId = null;

// 1) Watch for soft navigations and remember the route they created.
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    currentNavId = entry.navigationId;
    routeByNavId.set(entry.navigationId, new URL(entry.name).pathname);
  }
}).observe({ type: "soft-navigation", buffered: true });

// 2) Watch interactions; key each one to its owning navigation.
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.interactionId) continue;
    const navId = entry.navigationId ?? currentNavId;
    const route = routeByNavId.get(navId) ?? location.pathname;
    recordInteraction(route, entry.duration);
  }
}).observe({ type: "event", durationThreshold: 40, buffered: true });

Because the feature is still gated in some channels, always feature-detect with PerformanceObserver.supportedEntryTypes.includes("soft-navigation") and fall back to keying on location.pathname at interaction time. The pathname fallback is less precise — it can misattribute an interaction that fires mid-transition — but it keeps every browser reporting something per route. This mirrors the approach in Injecting Custom Metrics via PerformanceObserver, where the observer is the seam between the platform and your beacon.

Per-Route INP Budgets by Device Class

INP is a P75 field metric, so every ceiling you set must name the percentile and the device-plus-connection context it applies to — the same discipline used in Calculating INP Thresholds for Interactive Dashboards. Cheap surfaces (a static marketing route) deserve a tighter ceiling than a data-dense results grid; a uniform 200 ms budget would either strangle the simple routes or wave through the expensive ones. The table below assigns a P75 INP ceiling per route, split by device class, and reserves headroom the way the Mobile vs Desktop Budget Divergence reference recommends.

Read the ceilings as a promise at the 75th percentile: for /search on mid-range mobile over Fast 3G, three out of four real interactions must land at or under 260 ms. Set the low-end mobile /dashboard figure from your own field data rather than copying it — if your P75 on that route today is 420 ms, ratchet toward 300 ms in stages instead of failing every build on day one. When you have only a handful of samples per route, lean on the interpolation guidance in Choosing Between P75 and P90 Budget Targets before you trust a percentile.

Instrumenting With the web-vitals Attribution Build

You do not have to hand-roll percentile math in the browser. The web-vitals attribution build reports each INP occurrence with the interaction target, the event type, and the loading phase, and it already understands soft navigations when you enable the option. Ship the smallest possible beacon that carries the route, the value, and the device context, then aggregate P75 server-side — the same division of labor covered in Building P75/P99 Aggregation Pipelines.

// rum-inp-beacon.js
import { onINP } from "web-vitals/attribution";

function deviceClass() {
  const mem = navigator.deviceMemory ?? 8;
  const cores = navigator.hardwareConcurrency ?? 8;
  if (mem <= 2 || cores <= 4) return "low-end-mobile";
  if (matchMedia("(pointer: coarse)").matches) return "mid-range-mobile";
  return "desktop";
}

onINP((metric) => {
  const body = JSON.stringify({
    route: metric.attribution.navigationEntry?.name
      ? new URL(metric.attribution.navigationEntry.name).pathname
      : location.pathname,
    inp: Math.round(metric.value),
    rating: metric.rating,           // "good" | "needs-improvement" | "poor"
    target: metric.attribution.interactionTarget,
    device: deviceClass(),
    effectiveType: navigator.connection?.effectiveType ?? "unknown"
  });
  navigator.sendBeacon("/rum/inp", body);
}, { reportAllChanges: false, reportSoftNavs: true });

The reportSoftNavs: true flag is what makes the library emit a fresh INP candidate per soft navigation instead of one aggregate for the whole page lifetime. Keep the payload lean and batch on the collector side; the field aggregation, not the browser, owns the P75 rollup that your budget compares against, exactly as the Custom Performance Beacons and RUM reference lays out.

A Scripted CI Flow That Clicks Through Routes

Field data tells you where you stand; a scripted lab walk is what gates the pull request before regressions reach the field. Use Playwright to drive the real click paths, harvest the same soft-navigation and event entries through an injected observer, and assert each route's P75 against the table. Throttle CPU and network so the numbers mean something on mid-range mobile hardware.

// ci/soft-nav-inp.spec.js
const { test, expect } = require("@playwright/test");

const BUDGETS = { "/search": 260, "/product/42": 240, "/cart": 220 };

test("soft-navigation INP stays within per-route budgets", async ({ page }) => {
  const client = await page.context().newCDPSession(page);
  await client.send("Emulation.setCPUThrottlingRate", { rate: 4 });

  await page.addInitScript(() => {
    window.__inp = {};
    new PerformanceObserver((list) => {
      for (const e of list.getEntries()) {
        if (!e.interactionId) continue;
        const route = location.pathname;
        window.__inp[route] = Math.max(window.__inp[route] ?? 0, e.duration);
      }
    }).observe({ type: "event", durationThreshold: 40, buffered: true });
  });

  await page.goto("https://staging.example.com/");
  await page.getByRole("link", { name: "Search" }).click();
  await page.getByPlaceholder("Filter results").fill("blue running shoes");
  await page.getByRole("link", { name: "Nimbus 42" }).click();
  await page.getByRole("button", { name: "Add to cart" }).click();
  await page.getByRole("link", { name: "Cart" }).click();

  const observed = await page.evaluate(() => window.__inp);
  for (const [route, budget] of Object.entries(BUDGETS)) {
    expect(observed[route], `INP on ${route}`).toBeLessThanOrEqual(budget);
  }
});

A single scripted pass gives you one INP sample per route, which is a worst-single-interaction proxy rather than a true P75. Run the walk several times in a matrix and take the median of each route's worst interaction so a one-off long task from a cold cache does not fail the build. That matrix pattern, and the CPU throttling rate that makes a CI runner behave like mid-range mobile, are covered in the calibration side of the reference.

Verifying the Budget Holds

Wire the spec into CI so a route that blows its ceiling fails the check the same way a byte-size regression does. The step below runs the walk, prints a per-route verdict, and exits non-zero on the first breach — pair it with the route-level payload gates from Route-Level Bundle Budgets for React Router so a build cannot ship a heavier route without both signals turning red.

# .github/workflows/soft-nav-inp.yml
name: soft-nav-inp
on: [pull_request]
jobs:
  inp-budget:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - name: Run soft-navigation INP walk (3x, take median)
        run: |
          for i in 1 2 3; do
            npx playwright test ci/soft-nav-inp.spec.js --reporter=json > "run-$i.json" || true
          done
          node ci/median-verdict.js run-1.json run-2.json run-3.json

To confirm the field side agrees with the lab gate, query your collector for the last seven days and compare the measured P75 per route against the budget. If the lab passes but the field P75 on /search for mid-range mobile is 300 ms, your CI CPU throttle is too gentle — calibrate it upward. Cross-check against the P75 methodology in Using 75th Percentile for Real-World INP Targets so lab and field are speaking the same statistic, and treat any persistent gap as a signal that your emulation, not your budget, needs tuning. Finally, remember INP is only one axis of a route change: pair it with the transition-paint work in Measuring Client-Side Transition LCP so a route can never pass on responsiveness while shipping a blank surface.

Frequently Asked Questions