Intent to Ship: Layout Instability API CSS Pixel Attribution

[Ane Diaz De Tuesta]

# Contact emails

ane...@gmail.com

# Explainer

None (This is a small compatibility fix - the spec PR serves as the explainer).
The PR is a spec change, not an explainer. You can say "None" or link to a separate explainer if you have one.

# Specification

https://wicg.github.io/layout-instability/

# Summary

Change Layout Instability API attribution rectangles (`prevRect` and `currentRect`) from device pixels to CSS pixels. This aligns the API with other Web Platform measurement APIs (getBoundingClientRect, IntersectionObserver, ResizeObserver) that use CSS pixels as the standard coordinate system.

# Blink component

Blink>PerformanceAPIs

# Motivation

The current implementation uses device pixels, which:

- Creates inconsistencies across devices with different pixel ratios

- Makes it difficult for developers to correlate layout shift data with other measurements

- Deviates from the standard coordinate system used throughout the web platform

CSS pixels provide a consistent, device-independent unit that aligns with developer expectations and simplifies working with layout stability metrics alongside other DOM measurements.

# TAG review
Not applicable - This is a small compatibility fix to an existing API, not a new feature. The change aligns Layout Instability API attribution rectangles with the standard CSS pixel coordinate system used by other Web Platform APIs. This does not introduce new API surface or capabilities.

# TAG review status
Not applicable

# Chromium bug
https://issues.chromium.org/issues/399058544

# Risks

## Interoperability and Compatibility

**Interoperability risk:** Low. This is a measurement/telemetry change that doesn't affect site functionality. The API is used primarily by monitoring/analytics tools.

**Gecko:** Closed without a position (https://github.com/mozilla/standards-positions/issues/1318) - Mozilla supports CSS pixels for web APIs, though they don't implement the Layout Instability API.

**WebKit:** No signal (https://github.com/WebKit/standards-positions/issues/588)

**Web developers:** Positive feedback from WebPerf Slack community. The change simplifies working with layout stability metrics.

**Compatibility risk:** Low. Primary consumers are telemetry systems (RUM providers, analytics tools) that can adapt their processing. The change provides more consistent, useful data. Sites using the API directly will see coordinate values change but can easily adapt by removing device pixel ratio conversions.

**Rollback plan:** Feature can be disabled via flag if unexpected issues arise.

# Ergonomics

This change improves ergonomics by aligning with the CSS pixel coordinate system developers already use in other APIs (getBoundingClientRect, IntersectionObserver, ResizeObserver), reducing confusion and simplifying debugging.

# Activation

No user activation required - this is a measurement/telemetry API.

# Security

No security concerns - this changes the unit of measurement for existing data, does not expose new information.

# WebView application risks

None. This is a measurement/telemetry change that works consistently across all platforms including WebView.

# Debuggability

No changes to debuggability. The API continues to work the same way, just with CSS pixel coordinates instead of device pixels.

# Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

Yes.

# Is this feature fully tested by web-platform-tests?

Yes. Web Platform Tests have been updated to verify CSS pixel behavior for attribution rectangles.

WPT link: https://wpt.fyi/results/layout-instability/attribution-rectangles-css-pixels.html

# Flag name on chrome://flags

None (controlled by base::Feature)

# Finch feature name

None - shipping enabled by default for all users. This is a low-risk compatibility fix to a measurement API with good test coverage.

# Non-Finch justification

This is a compatibility fix to align the Layout Instability API with standard Web Platform coordinate systems. The change affects measurement data rather than user-facing functionality, and has low risk of breakage. Primary consumers are RUM/analytics tools that can adapt to the change.

# Requires code in //chrome?

No.

# Estimated milestones

Shipping on desktop: 145

Shipping on Android: 145

# Spec changes

Spec PR merged: https://github.com/WICG/layout-instability/pull/125
(Clarifies that attribution rectangles use CSS pixels, consistent with other Web Platform APIs)

# Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5155103518228480

# Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/g/blink-dev/c/EMlUrEwx_uE/m/pxBix6wWDAAJ?utm_medium=email&utm_source=footer

---

**This intent message was generated by Chrome Platform Status.**

Security and Privacy reviews have been approved via ChromeStatus gates.

Implementation CL: https://chromium-review.googlesource.com/c/chromium/src/+/6624567

---

[Barry Pollard]

Not that I've discussed this previously with Ane and this may require changes to those tools using these pixels to create screenshots or animations of CLS. I've reached out directly to the primary tools I'm aware off in this space (Chrome DevTools, DebugBear, WebPageTest) as well as more general outreach on the likes of the Web Performance slack. Will continue that further now the I2S is published.

It's a small change to accommodate this change, is not critical (the worst case is the wrong area of the screenshot/animation will be highlighted until the change is made) and brings the Layout Instability API inline with other Web Platform APIs and most would expect of this. So I'm supportive of this change, despite this risk.

Thanks,

Barry

[Yoav Weiss (@Shopify)]

LGTM1

The main risk here is for tools that get their input from this data and visualize it to users (where the data can be in either synthetic or RUM). We mainly care about RUM data here, but even there, the direct compat risk for actual users is minimal. In other words, this change will not create visible breakage for users, but may create one for developers that use tools that rely on this data.

On Mon, Dec 15, 2025 at 10:20 AM 'Barry Pollard' via blink-dev <blin...@chromium.org> wrote:

Not that I've discussed this previously with Ane and this may require changes to those tools using these pixels to create screenshots or animations of CLS. I've reached out directly to the primary tools I'm aware off in this space (Chrome DevTools, DebugBear, WebPageTest) as well as more general outreach on the likes of the Web Performance slack. Will continue that further now the I2S is published.

Thanks for the outreach!

 

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/1a72af4d-f574-488a-913e-a98135d3afban%40chromium.org.

[Yoav Weiss (@Shopify)]

+ane...@gmail.com - can you flip the review bits for Enterprise, Debuggability and Testing?

[Ane Diaz De Tuesta]

Thanks for your +1s!

I've just triggered the missing gates (Testing and Privacy). Once those are approved, I understand the next steps are:

1. Create a follow-up CL to enable the feature by default and get it reviewed and merged before the M145 branch point
2. Update the ChromeStatus entry to reflect "Enabled by default" status

Please let me know if there are any additional steps or if I should wait for further guidance before creating the enablement CL.


Best,

Ane

[Yoav Weiss (@Shopify)]

On Mon, Dec 15, 2025 at 1:55 PM Ane Diaz De Tuesta <ane...@gmail.com> wrote:

Thanks for your +1s!

I've just triggered the missing gates (Testing and Privacy). Once those are approved, I understand the next steps are:

1. Create a follow-up CL to enable the feature by default and get it reviewed and merged before the M145 branch point

Indeed. The "merge" part needs to only happen after all the gates are nice and green (Enterprise, Testing and Debuggability approved, and you got two more API owners to approve this intent).
 

2. Update the ChromeStatus entry to reflect "Enabled by default" status

Yup.

It would also be nice to make sure that MDN and other relevant docs get updated with the up-to-date unit. Given that this is a breaking change, it may make sense to also include it in some release notes. +Barry Pollard would most probably know where that may be.

 

Please let me know if there are any additional steps or if I should wait for further guidance before creating the enablement CL.

No need to wait before creating the CL, just before merging it. 

[Barry Pollard]

It would also be nice to make sure that MDN and other relevant docs get updated with the up-to-date unit. Given that this is a breaking change, it may make sense to also include it in some release notes. 

+Barry Pollard

 would most probably know where that may be.

1. By completing this chromestatus Dev Rel will automatically already included this in the Chrome Beta release post (example) and the What's New in Chrome post (example). Just make sure to get this chromestatus entry up to date, if it slips to 146.

2. Ane, can you also include updates to the CLS Change log in your CL:
https://chromium.googlesource.com/chromium/src/+/main/docs/speed/metrics_changelog/cls.md

3. I'm less sure about MDN. Its documentation on this doesn't go into this level of detail. If we were changing the layout shift values used to calculate CLS itself I'd agree we should change MDN, but for this lesser-used attribution data I think 1 and 2 will suffice.

 

[Ane Diaz De Tuesta]

Thanks for your answers!

- I've created [a CL to enable the feature by default](https://chromium-review.googlesource.com/c/chromium/src/+/7261417) and included updates to the CLS change log. Let me know if the changelog looks good to you.
- I won't assign any reviewer to the CL until all the missing gates are approved.
- After some reflection, I think completing the MDN docs would be very useful. Before working on this feature, I had a hard time finding any information about the units of the reported pixels. Looking at [the getBoundingClientRect documentation](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect), I noticed the units are mentioned right from the beginning, which removes any ambiguity.

- I'd like to update the MDN docs similarly. While the posts Barry mentioned are helpful, explicit documentation would benefit developers who might not read those posts. (I'm happy to do this update if you're in agreement.)

Best,

Ane

[Barry Pollard]

Thanks for your continued work on this Ane!

- After some reflection, I think completing the MDN docs would be very useful. Before working on this feature, I had a hard time finding any information about the units of the reported pixels. Looking at [the getBoundingClientRect documentation](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect), I noticed the units are mentioned right from the beginning, which removes any ambiguity.

I'm actually struggling to see where this is mentioned "right from the beginning" on that page? Do you mean because it's relative to the viewport? Or by the examples? Perhaps this page could be clearer too! Or I'm just missing something (definitely possible!).

- I'd like to update the MDN docs similarly. While the posts Barry mentioned are helpful, explicit documentation would benefit developers who might not read those posts. (I'm happy to do this update if you're in agreement.)

More documentation is always welcome! I'm definitely happy to define the units the API returns on MDN to avoid any ambiguity. Especially if it matches other docs (like the one I can't see above!).

What I'm not so sure about is whether to document this change. That's typically handled in the Browser Compat Data at the bottom of the MDN doc pages, but how exactly to handle this change is a little unclear. Typically that would be done either by adding a new sub-feature (e.g. "css-in-pixels") or saying this was only partially supported in Chrome until 145. I don't think either is an accurate reflection of this feature: it's not a sub-feature (it's not something we expect other browsers to support one way or another), nor was the support in Chrome partial before this. It's just this was unclear in specification and, in hindsight, would be better in what you are moving too. The other option is to add a note for previous versions, but MDN discourages those for fully supported APIs (understandably so, since they only will confuse going forward). So personally I'm still against explicitly documenting this change in MDN and instead think it's more like a bug we're fixing that is best handled in the other docs mentioned previously.

But happy to hear others opinions on this.

And I'm also happy to help you on the MDN updates if you want as I'm quite familiar with that process (ping me offline if you want that, as we don't need to work though those on this mailing list).

[Mike Taylor]

LGTM2 (and thanks Barry for doing outreach to RUM providers).

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAOmohSKPSqnxw8PAizjj%3DT9yPLWMobxv3BOgJ7J-MEkD0_qB0w%40mail.gmail.com.

[Ane Diaz De Tuesta]

As discussed with Barry Pollard offline, in all web docs we assume that pixels = CSS pixels!

When it's physical pixels that should be the exception that's documented.

So after a second reflection, we finally got back to the conclusion that MDN doesn't need to be updated.

Now, I am looking for my last API Owner approval, can I ping someone or approvers will show naturally?

Thanks!
Best,
Ane

[Mike Taylor]

This intent is visible in the API Owner review queue, so no need to ping (unless the thread goes silent for a ~week). 

[Chris Harrelson]

LGTM3

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/159d7198-045f-46a8-b1e9-a0f8a85c06fe%40chromium.org.

[Ane Diaz De Tuesta]

Hi all,

I'm following up on the Debuggability gate, which is currently showing as overdue by a day on ChromeStatus. I'd like to move forward with completing the Intent to Ship process.

For context, this change modifies Layout Instability API attribution rectangles from device pixels to CSS pixels, a units change that aligns with other Web Platform APIs (getBoundingClientRect, IntersectionObserver, etc.).

From a debuggability perspective:

• The API continues to work identically, just reporting CSS pixels instead of device pixels
• DevTools Layout Instability tracking remains unchanged
• Developers can inspect the values the same way through the PerformanceObserver API

If there are specific debuggability concerns or additional information needed, I'm happy to provide it. Otherwise, any guidance on how to move this gate forward would be greatly appreciated.

Thanks!

Ane :-)

[Mike Taylor]

Hi Ane,

The debuggability reviewer is OOO for the next week or so, but based on your answers I've gone ahead and approved the bit.

thanks,
Mike

[Barry Pollard]

Thanks Mike! I was just chasing the Chrome Tooling team on this to see if anyone else could approve in his absence. They're aware of the change and have been liaising with Ane on it. So good to approve.

[Ane Diaz De Tuesta]

This is amazing — thank you both!
Since all the gates are approved, the final step to ship the feature is to merge the CL that promotes ReportLayoutShiftRectsInCssPixels to stable: https://chromium-review.googlesource.com/c/chromium/src/+/7261417

Mike, I added you as the code owner, since you’ve been incredibly helpful throughout this process.

I can’t believe I’ll see this live soon 🤩 — my Christmas gift after Christmas 🙂

Thank you!

[Ane Diaz De Tuesta]

Hi all,

Thank you to chrishtr@, miketaylr@, and yoavweiss@ for the LGTMs! (and barryp@ for your guidance!)

I'm happy to report that this feature has now shipped:
✅ All review gates completed (Privacy, Security, Enterprise, Testing, Debuggability)
✅ Flag CL merged: https://chromium-review.googlesource.com/c/chromium/src/+/7261417
✅ CLS changelog updated
✅ Shipped in Chrome 145

The Layout Instability API now reports attribution rectangles in CSS pixels by default, improving consistency with other Web Platform APIs.

Should I update the ChromeStatus page to reflect that all changes have been addressed? If yes, what fields should I update?

Thanks again to everyone who provided feedback and guidance throughout this process!

[Michal Mocny]

Well done, thanks for the contribution!

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/44922610-8f72-4c25-99a2-51ace64ce428n%40chromium.org.

[Rick Byers]

Very cool, thanks for getting this fixed!

On Tue, Jan 6, 2026 at 10:34 AM 'Michal Mocny' via blink-dev <blin...@chromium.org> wrote:

Well done, thanks for the contribution!

On Tue, Jan 6, 2026 at 10:09 AM Ane Diaz De Tuesta <ane...@gmail.com> wrote:

Hi all,

Thank you to chrishtr@, miketaylr@, and yoavweiss@ for the LGTMs! (and barryp@ for your guidance!)

I'm happy to report that this feature has now shipped:
✅ All review gates completed (Privacy, Security, Enterprise, Testing, Debuggability)
✅ Flag CL merged: https://chromium-review.googlesource.com/c/chromium/src/+/7261417
✅ CLS changelog updated
✅ Shipped in Chrome 145

The Layout Instability API now reports attribution rectangles in CSS pixels by default, improving consistency with other Web Platform APIs.

Should I update the ChromeStatus page to reflect that all changes have been addressed? If yes, what fields should I update?

Nope, the Chromestatus entry looks good and complete to me. Of course please keep your ears open for any issues which may arise prior to or around M145 hitting stable on Feb 10, and worst case be prepared to flip it off temporarily and update Chromestatus for the delay. But of course that's not likely to be necessary, so we don't require any chromestatus updates for the happy path of all going as planned.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAEeF2TcK67AJjq%2BHwm7cWVaKKY_O7YGqTr8a7OTFE7nzikb1Xg%40mail.gmail.com.