Scroll Timing API proposal #1222

nhelfman · 2026-01-06T08:32:36Z

Initial proposal for performance Scroll Timing API.
Besides the short explainer, included also design notes document, open question document and a demo with polyfill.

aluhrs13 · 2026-01-07T17:21:12Z

Can you add "Authors" and "Participate" sections? https://github.com/w3ctag/explainer-explainer/blob/main/template.md

…ructured table of contents; outline goals and non-goals for the Scroll Timing Performance API.

…I and clarify accessibility, internationalization, privacy, and security considerations.

…demo.html and polyfill.js

…sers in demo.html

…upport

…when API is ready

nhelfman · 2026-01-12T14:40:09Z

Can you add "Authors" and "Participate" sections? https://github.com/w3ctag/explainer-explainer/blob/main/template.md

Done. See latest iteration.

Scroll Timing Performance API

A proposal to standardize scroll performance measurement on the web.

Authors

Noam Helfman (Microsoft)

Participate

Issue tracker

PerformanceScrollTiming/explainer.md

mhochk · 2026-01-14T20:29:07Z

PerformanceScrollTiming/explainer.md

+  readonly attribute DOMHighResTimeStamp duration;
+  readonly attribute unsigned long framesExpected;
+  readonly attribute unsigned long framesProduced;
+  readonly attribute double checkerboardTime;


Why not DOMHighResTimeStamp for checkerboardTime so that the unit (ms) is baked into the type?

Right. Updated.

mhochk · 2026-01-14T20:31:32Z

PerformanceScrollTiming/explainer.md

+  readonly attribute long distanceX;
+  readonly attribute long distanceY;


NIT on naming - 'distance' implies a non-negative number. What about deltaX like the wheel event, or scrollX?

Makes sense. Updated.

mhochk · 2026-01-14T20:33:46Z

PerformanceScrollTiming/explainer.md

+interface PerformanceScrollTiming : PerformanceEntry {
+  // Inherited from PerformanceEntry
+  readonly attribute DOMString entryType;  // Always "scroll"
+  readonly attribute DOMString name;       // Empty string


Based on the name values returned by other sub-classes of PerformanceEntry, it sounds like "scroll" would be more appropriate than an empty string.

https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry/name

Makes sense. It is only set empty for LargestContentfulPaint. Perhaps if we will have different scroll metrics that can be produced we would need different name. I'll set it to scroll.

mhochk · 2026-01-14T20:44:52Z

PerformanceScrollTiming/explainer.md

+|-----------|------|-------------|
+| `entryType` | DOMString | Always `"scroll"` (inherited from PerformanceEntry) |
+| `name` | DOMString | Empty string (inherited from PerformanceEntry) |
+| `startTime` | DOMHighResTimeStamp | Timestamp of the first input event that initiated the scroll |


I'm assuming here, but I would guess "or 0 for programmatic invocation" is the intention? If so, consider adding that as a callout if you don't think it's makes it too long.

My thinking was the startTime for programmatic scrolls should be the timestamp of the scroll invocation (e.g. time of scrollTo call).

Updated the description.

mhochk · 2026-01-14T20:51:16Z

PerformanceScrollTiming/explainer.md

+| `checkerboardTime` | double | Total duration (ms) that unpainted areas were visible during scroll |
+| `distanceX` | long | Horizontal scroll distance in pixels (positive = right, negative = left) |
+| `distanceY` | long | Vertical scroll distance in pixels (positive = down, negative = up) |
+| `scrollSource` | DOMString | Input method: `"touch"`, `"wheel"`, `"keyboard"`, `"other"`, or `"programmatic"` |


Mostly just curious, but what value gets used when scrolling to a header, via a # in the URL?

I'm thinking primarily about the typical table-of-contents pattern where the user might click on a link and get scrolled down the page - would it make sense to make "mouse" an option for that, rather than "other", given the widespread usage of that design pattern? And if they did it via keyboard would it come through as "keyboard"? (I ask this one more from glancing in the polyfill and seeing a listed subset of keys that doesn't include things like 'enter').

Related - if tabbing through items on a page, will that go down as "keyboard"?

Good questions. I have not considered these scenarios yet. Updated the "open questions section".

mhochk · 2026-01-14T21:12:43Z

PerformanceScrollTiming/explainer.md

+| `name` | DOMString | Empty string (inherited from PerformanceEntry) |
+| `startTime` | DOMHighResTimeStamp | Timestamp of the first input event that initiated the scroll |
+| `firstFrameTime` | DOMHighResTimeStamp | Timestamp when the first visual frame reflecting the scroll was presented |
+| `duration` | DOMHighResTimeStamp | Total scroll duration from `startTime` until scrolling stops (includes momentum/inertia) |


And if startTime is 0 for programmatic invocations, what about duration being based on firstFrameTime instead? If devs want to include the initial lag time as well they can check for a non-zero startTime and then add the firstFrameTime - startTime diff.

Updated the description.

ogerchikov · 2026-01-14T21:47:58Z

PerformanceScrollTiming/DESIGN_NOTES.md

+- **Keyboard/wheel scrolls**: Usually lower, more consistent velocity with discrete steps
+- **Programmatic scrolls**: Smooth scroll behavior produces predictable, constant velocity
+- **Search navigation**: Users jumping to search results often produce short-duration, high-velocity scrolls
+


It's worth mentioning scrollbar scrolls, they produce the most checkerboarding, according to Chromium metrics.

It's worth mentioning scrollbar scrolls, they produce the most checkerboarding, according to Chromium metrics.

Added a bullet capturing this.

ogerchikov · 2026-01-14T22:27:19Z

PerformanceScrollTiming/explainer.md

+  readonly attribute DOMHighResTimeStamp startTime;
+  readonly attribute DOMHighResTimeStamp firstFrameTime;
+  readonly attribute DOMHighResTimeStamp duration;
+  readonly attribute unsigned long framesExpected;


Smoothness metrics, such as framesExpected, framesProduced, and checkerboardTime, provide meaningful measurements of smoothness across various animations and interactions scenarios, including scroll-driven animations and JavaScript/CSS-based animations. While implementing a full Animation Smoothness API is not the immediate goal, introducing these metrics is a significant step toward measuring key aspects of animation performance and user-perceived smoothness.

I’m curious if you’ve considered separating generic smoothness attributes from PerformanceScrollTiming into a distinct interface. This approach allows us to address immediate needs while laying the groundwork for potential future API development.

interface AnimationSmoothnessEntry : PerformanceEntry { readonly attribute unsigned long framesExpected; readonly attribute unsigned long framesProduced; readonly attribute double checkerboardTime; } interface PerformanceScrollTiming : AnimationSmoothnessEntry { ... }

Good idea. If there is a consensus that the path for Animation Smoothness API will include something like this then it certainly reasonable to structure it like this.

There is still an orthogonal open question on what expectedFrame should mean. In my prototype I measure the v-sync rate and use that as the expected so if the frame rate changes the expected changes as well. However, it may be that it makes more sense to decide on a constant smoothness frame rate (e.g. 60 FPS) and use that to calculate the expectedFrames value.

I can update to the proposal

ogerchikov · 2026-01-14T22:31:38Z

PerformanceScrollTiming/explainer.md

+| `checkerboardTime` | double | Total duration (ms) that unpainted areas were visible during scroll |
+| `distanceX` | long | Horizontal scroll distance in pixels (positive = right, negative = left) |
+| `distanceY` | long | Vertical scroll distance in pixels (positive = down, negative = up) |
+| `scrollSource` | DOMString | Input method: `"touch"`, `"wheel"`, `"keyboard"`, `"other"`, or `"programmatic"` |


I think the API should be able to report scrollbar scrolls, as they are the most common source of checkerboarding.

This is indeed my preference. Some feedback that was raised is that providing explicit "scrollbar" (or perhaps "trackpad", "autoscroll" etc.) might be a privacy concern since it exposed more information than currently is exposed. To mitigate this upfront I grouped all of them to the "other" since that does not expose any additional information that wasn't existing before. We should have a discussion about this concern and perhaps can think of mitigations which will alleviate the privacy concern.

Expanded description in the open questions "Scrollbar as a Distinct Scroll Source" section capturing this.

…ibute description to indicate it always returns "scroll"

…ormanceScrollTiming interface

…d focus-driven scrolling

…alue, addressing privacy concerns and diagnostic value.

…X/deltaY across documentation and implementation for consistency in the PerformanceScrollTiming API.

…face to specify it always returns "scroll"

initial commit - scroll timing

299bb55

nhelfman marked this pull request as ready for review January 6, 2026 08:33

Noam Helfman added 10 commits January 11, 2026 10:10

first pass in adapting to standard explainer.md format

4d4d2ee

Enhance explainer.md with author details, participation links, and st…

84b1fb8

…ructured table of contents; outline goals and non-goals for the Scroll Timing Performance API.

Add user research references and clarify dependencies in explainer.md

ea1c4c4

Document alternatives considered for the Scroll Timing Performance AP…

e520b7c

…I and clarify accessibility, internationalization, privacy, and security considerations.

minor tweaks.

77d6a94

Refactor smoothness score calculation for clarity and consistency in …

0d5c577

…demo.html and polyfill.js

Implement manual smooth scrolling for consistent behavior across brow…

eb2181f

…sers in demo.html

added acknowledgements

8814452

Load polyfill conditionally based on native PerformanceScrollTiming s…

59bba89

…upport

Enhance demo.html to load polyfill asynchronously and dispatch event …

8159118

…when API is ready

mwjacksonmsft reviewed Jan 12, 2026

View reviewed changes

PerformanceScrollTiming/explainer.md Show resolved Hide resolved

mhochk reviewed Jan 14, 2026

View reviewed changes

ogerchikov reviewed Jan 14, 2026

View reviewed changes

Noam Helfman added 8 commits January 15, 2026 08:27

Clarify PerformanceScrollTiming interface by updating the 'name' attr…

542f3ce

…ibute description to indicate it always returns "scroll"

Update checkerboardTime attribute type to DOMHighResTimeStamp in Perf…

4909dfc

…ormanceScrollTiming interface

clarified startTime for programmatic scroll

574afbd

Add scrollSource classification discussion for fragment navigation an…

e9eda88

…d focus-driven scrolling

Clarify discussion on adding "scrollbar" as a distinct scrollSource v…

1d6ef4a

…alue, addressing privacy concerns and diagnostic value.

Refactor scroll distance attributes from distanceX/distanceY to delta…

421b769

…X/deltaY across documentation and implementation for consistency in the PerformanceScrollTiming API.

Clarify name attribute description in PerformanceScrollTiming inter…

a8cd9bd

…face to specify it always returns "scroll"

Add scrollbar scrolls to velocity-related patterns in design notes

ef7426c

mwjacksonmsft self-assigned this Jan 15, 2026

mwjacksonmsft approved these changes Jan 15, 2026

View reviewed changes

mwjacksonmsft merged commit b6ff8d8 into MicrosoftEdge:main Jan 15, 2026
1 check passed

		readonly attribute long distanceX;
		readonly attribute long distanceY;

Scroll Timing API proposal #1222

Scroll Timing API proposal #1222

Uh oh!

Conversation

nhelfman commented Jan 6, 2026

Uh oh!

aluhrs13 commented Jan 7, 2026

Uh oh!

nhelfman commented Jan 12, 2026

Scroll Timing Performance API

Authors

Participate

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhelfman Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhelfman Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhelfman Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhelfman Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhelfman Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhelfman Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nhelfman Jan 15, 2026 •

edited

Loading

nhelfman Jan 15, 2026 •

edited

Loading

nhelfman Jan 15, 2026 •

edited

Loading

nhelfman Jan 15, 2026 •

edited

Loading

nhelfman Jan 15, 2026 •

edited

Loading

nhelfman Jan 15, 2026 •

edited

Loading