Long Animation Frames (LoAF): Attributing Slow Frames to the Script That Caused Them

This topic extends the interactivity tooling in Core Web Vitals & Measurement with the one browser API that tells you which script made a frame slow, not merely that it was slow.

For years the only field signal for main-thread congestion was the Long Tasks API: an entry saying "something ran for 180ms" with an attribution field that, in practice, almost always read unknown. That was enough to prove a problem existed and useless for assigning it to a team. The Long Animation Frames API (LoAF), stable in Chromium since version 123, replaces the task as the unit of measurement with the frame — the full span from the start of work to the next paint — and attaches a list of the scripts that ran inside it, with their source URL, function name, character position, invoker type and how long each spent in forced style and layout.

That shift matters because Interaction to Next Paint is itself a frame-based measurement. An interaction fails the 200ms budget when the frame that should present its result is late, and the reason a frame is late is rarely one task: it is a sequence of event listeners, promise continuations, a framework commit and a rendering phase that together overran. LoAF reports exactly that sequence, so the gap between "INP is 340ms at p75" and "the onChange handler in filters.js spends 190ms in forced layout" closes from days to minutes.

The Metric Degradation LoAF Explains

The failure mode this topic addresses is an INP p75 above 200ms where the Performance panel shows a busy main thread but nothing obviously wrong in your own code. Typical shapes:

• Input delay dominates (>100ms) because an unrelated script — a tag manager, a polling widget, a hydration chunk — owns the thread when the user taps. The Long Tasks API would report an unattributed task; LoAF names the script and the invoker that started it.
• Processing time dominates because several listeners fire for one interaction (a pointerdown, a click and a framework's synthetic dispatcher) and each looks cheap alone. LoAF sums them inside one frame.
• Presentation delay dominates because the handler finished quickly but invalidated a large layout. LoAF's renderStart and styleAndLayoutStart timestamps isolate the rendering tail, and each script's forcedStyleAndLayoutDuration shows when layout was forced inside JavaScript instead.

A frame is considered long once it exceeds 50ms — the same budget the long-task definition uses — and a long frame overlapping an interaction is what pushes it past the 200ms boundary. The blockingDuration field approximates how much of that frame was unavailable for input, which is the figure that correlates with input delay in the field.

Prerequisites

• Chromium 123+ for the long-animation-frame entry type. Firefox and Safari do not expose it, so treat LoAF data as a Chromium-only diagnostic sample; it remains representative because the scripts are the same across engines.
• The web-vitals library v4 or later, attribution build. Its INP attribution includes longAnimationFrameEntries for the interaction's frame, which saves you correlating timestamps by hand.
• Same-origin or CORS-enabled scripts. A cross-origin script loaded without crossorigin and a matching Access-Control-Allow-Origin header reports its sourceURL but an empty function name and position — enough to blame a vendor, not to find the line.
• DevTools with the Performance panel's "Show custom tracks" option if you want to plot LoAF entries alongside the flame chart during lab reproduction.

1. Environment Setup: Observe Long Frames Without Distorting Them

Register a single PerformanceObserver with buffered: true as early as possible so frames that happened before your observer existed are still delivered. Keep the callback cheap — it runs on the main thread you are trying to measure.

// loaf-observer.js — load early, before the app bundle if you can.
const frames = [];
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.duration < 50) continue;            // only long frames
    frames.push(entry);
    if (frames.length > 200) frames.shift();     // bounded memory on long sessions
  }
}).observe({ type: 'long-animation-frame', buffered: true });
// trade-off: buffered:true replays a limited buffer of past entries, not the
// whole session. If you register late (after hydration), the slowest load-time
// frames may already have been evicted — inline the observer in <head> when
// load-phase attribution matters.

2. Capture a Baseline: Which Frames Overlap Interactions?

Not every long frame matters. A 300ms frame during a background data refresh with no user input is a throughput problem, not an INP problem. The baseline you want is the set of long frames that contain an interaction: LoAF exposes firstUIEventTimestamp, which is non-zero when the frame processed user input.

const interactive = frames.filter((f) => f.firstUIEventTimestamp > 0);
console.table(interactive.map((f) => ({
  start: Math.round(f.startTime),
  duration: Math.round(f.duration),
  blocking: Math.round(f.blockingDuration),
  scripts: f.scripts.length,
  renderTail: Math.round(f.startTime + f.duration - f.renderStart),
})));
// trade-off: firstUIEventTimestamp marks frames that *handled* input, but a
// long frame immediately BEFORE the input is what inflates input delay. Keep
// the preceding frame too when you are chasing input delay rather than processing.

Record this on a throttled lab profile (4x CPU) for the interactions your RUM flags as slowest. Two or three frames will dominate; that is your shortlist.

3. Isolate the Bottleneck: Read the Script Entries

Each entry's scripts array is the heart of the API. For each script you get invoker (for example BUTTON#save.onclick or Response.json.then), invokerType (event-listener, user-callback, resolve-promise, classic-script, module-script), sourceURL, sourceFunctionName, sourceCharPosition, duration, and forcedStyleAndLayoutDuration.

Sort the scripts in the slowest interactive frames by duration and look at the top three. In practice they fall into a small number of recognisable patterns: one heavy listener (fix with yielding), a third-party script evaluating during the interaction (fix with deferral), or a cheap listener with a large forcedStyleAndLayoutDuration (fix the read/write order). The guide on finding slow scripts with LoAF script attribution walks through each pattern on a real trace.

4. Apply the Fix Matched to the Phase

LoAF does not fix anything; it routes you to the right existing technique:

• Heavy event listener → split it with the await-yield loop from optimizing INP with scheduler.yield().
• Third-party script evaluated during the frame → load it on interaction or idle, as in third-party script performance.
• Large forcedStyleAndLayoutDuration → reorder DOM reads before writes; see layout thrashing and forced reflow.
• Short scripts, long render tail → reduce the size of the DOM update, the subject of diagnosing presentation delay with LoAF.

Deconstructing a Long Animation Frame

A LoAF entry has enough timestamps to split its duration into four phases, and each has a practical budget if the whole frame is to stay under roughly 100ms so the interaction lands under 200ms once input delay is added.

The blockingDuration field is distinct from all of these: it is the sum, across the long tasks inside the frame, of time beyond the first 50ms of each, plus rendering time. Use it as a ranking key for input-delay risk, and the phase split above to decide what to change.

Advanced Diagnostics and Edge Cases

Cross-origin scripts with empty attribution. When sourceFunctionName is blank and sourceCharPosition is -1, the script was loaded without CORS. Adding crossorigin="anonymous" fixes attribution only if the vendor serves Access-Control-Allow-Origin; if they do not, the request will fail outright, so test before shipping.

Frames with zero scripts. A long frame with an empty scripts array means the cost was entirely rendering — commonly a CSS animation on a layout property or a content-visibility region being rendered for the first time. Look at the render tail, not your JavaScript.

Framework dispatchers hiding the real handler. React and Vue attach a single root listener, so invoker reads something like DIV#root.onclick for every interaction. Use sourceFunctionName and sourceCharPosition with source maps to resolve the real component; or set performance.mark() calls in suspect handlers and match timestamps.

Script entries under 5ms are omitted. The specification only lists scripts above a small duration threshold, so a frame built from hundreds of tiny callbacks may report a long duration with few scripts. That shape — death by a thousand microtasks — usually indicates a reactive store notifying too many subscribers.

Extension noise. Browser extensions inject content scripts that appear in lab LoAF data with chrome-extension:// URLs. Filter them out of RUM aggregation, but do not ignore them in support tickets: a slow extension is a real user's real INP.

Validation and Budgeting

Lock the fix in at two levels. In the lab, assert that no interactive frame in a scripted interaction exceeds a budget, using Puppeteer to drive the interaction and read entries from the page:

// ci/assert-loaf.mjs — fail the build if the scripted interaction produces a long frame.
const worst = await page.evaluate(() => new Promise((resolve) => {
  const seen = [];
  new PerformanceObserver((l) => seen.push(...l.getEntries()))
    .observe({ type: 'long-animation-frame', buffered: true });
  document.querySelector('#apply-filters').click();
  setTimeout(() => resolve(Math.max(0, ...seen
    .filter((f) => f.firstUIEventTimestamp > 0).map((f) => f.duration))), 1000);
}));
if (worst > 100) throw new Error(`interactive frame ${Math.round(worst)}ms > 100ms budget`);
// trade-off: CI hardware is faster than a mid-tier phone, so a 100ms lab budget
// roughly corresponds to a 200ms+ field frame. Calibrate the threshold against
// your own RUM rather than copying this number.

In the field, ship the top script entries for the INP interaction in your RUM beacon — the guide on sending LoAF data in RUM beacons covers the payload budget — and alert when the share of INP frames attributed to a single sourceURL jumps release-over-release.

Code Example: Joining LoAF to the INP Interaction

The web-vitals attribution build already does the correlation for you; this example shows the minimal useful extraction.

import { onINP } from 'web-vitals/attribution';

onINP(({ value, attribution }) => {
  const scripts = (attribution.longAnimationFrameEntries || [])
    .flatMap((f) => f.scripts)
    .sort((a, b) => b.duration - a.duration)
    .slice(0, 3)
    .map((s) => ({
      src: s.sourceURL.split('?')[0],
      fn: s.sourceFunctionName || '(anonymous)',
      type: s.invokerType,
      ms: Math.round(s.duration),
      layout: Math.round(s.forcedStyleAndLayoutDuration),
    }));
  navigator.sendBeacon('/rum', JSON.stringify({ inp: Math.round(value), scripts }));
});
// trade-off: stripping query strings keeps cardinality manageable but merges
// distinct vendor endpoints that differ only by parameters. Keep the full URL
// for first-party scripts if your bundles are fingerprinted by query string.

Patterns That Recur in Production LoAF Data

Once LoAF attribution has been flowing for a week, the same handful of shapes account for most failing interactions. Recognising them by their signature saves a reproduction cycle.

The tag-manager pile-up. The frame's slowest script has a sourceURL on a tag-manager host and an invokerType of classic-script or user-callback, and firstUIEventTimestamp falls inside it. The user tapped while a container was evaluating a dozen tags queued by a consent change or a page-view trigger. The fix is upstream: fire those tags from an idle callback rather than synchronously on the trigger, or move them server-side. Nothing in your own handler will help.

The hydration collision. On the first interaction after load, the slowest script is a framework chunk with an invoker such as Window.requestIdleCallback or a module script evaluation, and input delay is large while processing is small. The interaction arrived mid-hydration. You either hydrate less (selective hydration with React Suspense and islands are the main tools) or make hydration yield so the input can slip in between chunks.

The reactive fan-out. Many scripts of a few milliseconds each, all from the same store or signals library, with a total duration above 100ms. One state change notified hundreds of subscribers. Narrow the subscription (selectors, shallowRef, memoised derived state) rather than speeding up any one subscriber.

The layout ping-pong. A modest script duration with a forcedStyleAndLayoutDuration making up most of it — say 70ms of an 85ms listener. Some loop reads offsetHeight or getBoundingClientRect() after writing a class. The fix is mechanical: read everything first, then write, or move the measurement into a ResizeObserver.

The silent renderer. Script entries total under 30ms but the frame is 180ms because the render tail is huge. The DOM change was legitimately small in code and enormous in effect — toggling a class on <body> that every rule in a 400KB stylesheet depends on, or inserting 2,000 table rows. Containment and virtualisation, not JavaScript, move this number.

FAQ

Guides in This Topic

• Finding slow scripts with LoAF script attribution — turn a list of script entries into a ranked suspect list.
• LoAF vs the Long Tasks API — what changed, and whether to keep the old observer.
• Sending LoAF data in RUM beacons — attribution without blowing the beacon size budget.
• Diagnosing presentation delay with LoAF — the render tail your scripts do not show.

Related

• Profiling event handlers for INP — the DevTools workflow LoAF data feeds into.
• Attributing INP to a component with the attribution build — mapping phases to owners in the field.
• RUM beacons and field data collection — the pipeline that carries LoAF attribution home.
• Soft navigations and SPA metrics — assigning long frames to the route that caused them.