Long Animation Frames: how to debug slow INP in the field
INP tells you a page is slow, not why. Here is how the Long Animation Frames API and the web-vitals library point to the script behind a bad interaction.
Search Console can tell you that a group of pages has poor Interaction to Next Paint. It cannot tell you which script caused it. That gap is where most INP projects stall. The Long Animation Frames API (LoAF) closes much of it by naming the scripts that held up the browser during a slow interaction.
Why INP is hard to debug
INP measures the delay between a tap, click, or key press and the next frame the browser paints. It reports one of the slowest interactions of a visit, so the cause can be anywhere on the page. A lab test rarely reproduces it, because a lab test does not click the cookie banner, open the mega menu, and type in the search box in the order a real visitor does.
The older Long Tasks API reports that the main thread was blocked, but it gives almost no detail about who blocked it. You end up guessing, then profiling by hand.
What the Long Animation Frames API reports
A long animation frame is a frame that took longer than 50 milliseconds to produce. The API lets your own code read an entry for each one. It is available in Chromium browsers. Other browsers do not support it at the time of writing, so treat the data as a Chrome-only sample.
Each entry breaks the frame into parts you can act on:
- Scripts: a list of every script that ran in the frame, with its source URL, the function name, and how it was invoked (an event listener, a timer, a promise callback).
- Duration and blocking duration: how long the frame took, and how much of that time the main thread was blocked.
- Render start and style and layout start: timestamps that show whether the cost was JavaScript or the work the browser did afterward.
- Input delay context: whether the frame overlapped the interaction you care about.
The script list is the useful part. If one third-party tag shows up in most of your slow frames, you have a name to take to the vendor or to your tag manager.
How to collect it from real visitors
You do not need to write the observer yourself. Google's open-source web-vitals library has an attribution build. When it reports INP, it includes the interaction target, the three phases of the interaction, and the matching long animation frame entries when the browser supports them.
- Load the attribution build of the web-vitals library on your pages.
- Register the INP callback and read the attribution object it passes.
- Send a small payload to your analytics endpoint: the page template, the interaction target selector, the three phase timings, and the top script source URLs.
- Only send the data for interactions above 200 milliseconds. Good interactions are noise here.
- Group the reports by page template and by script URL after a week or two of traffic.
Keep the payload small and drop query strings from URLs. Do not send anything that identifies a person, such as the text a visitor typed into a field.
Reading the three phases
Every interaction has three parts, and each points to a different fix.
Input delay
The browser could not start handling the event because the main thread was busy. Look for long scripts that run at load or on a timer. Splitting that work into smaller chunks, or deferring it, helps most.
Processing time
Your event handlers ran for too long. Check the script entries for heavy handlers. Move non-urgent work, such as analytics calls, out of the handler so the page can paint first.
Presentation delay
The handler finished, but the browser spent a long time on style, layout, and paint. Large DOM trees and expensive CSS selectors are the usual suspects. A big gap between style and layout start and the end of the frame points here.
Limits to keep in mind
- Chromium only. Safari and Firefox visitors will not appear in the script data, though they still count toward your overall INP picture where those browsers report it.
- Cross-origin scripts can be obscured. Some entries will show limited detail for scripts from other origins, so you may see the frame was slow without a clean name for the culprit.
- It is a diagnosis tool, not a ranking factor. Google uses INP from its own field data, not your LoAF reports. LoAF only helps you improve the number Google already sees.
- Sampling matters. Collect on a share of visits if your traffic is large, so the reporting itself does not add load.
Field data tells you where it hurts. Long animation frames tell you which script is doing the hurting.
What to do this week
Start with one slow page group from the Core Web Vitals report in Search Console. Add the web-vitals attribution build to that template and collect for a week or two. Then sort the slow interactions by script source. Pick the single script that appears most often and decide whether to defer it, replace it, or remove it. Re-check INP in Search Console after the next 28-day window. One script fixed with evidence beats a dozen guesses made in a profiler.