chore: Revert "Revert "fix: scrollIntoView should respect scroll-margin (#8715)"" by nwidynski · Pull Request #9146 · adobe/react-spectrum

nwidynski · 2025-11-04T23:44:45Z

This PR refactors scrollIntoView and scrollIntoViewport to support scrollMargin, while working around the regressions mentioned in #8689 (comment). Additionally, a new inline & block option for alignment of a container element has been added.

By leveraging bounding rectangles, the internal calculations are now streamlined with DOMLayoutDelegate and significantly simplified.

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

🧢 Your Project:

nwidynski · 2025-11-04T23:49:19Z

packages/@react-aria/utils/src/scrollIntoView.ts

+      let {left: newLeft, top: newTop} = targetElement.getBoundingClientRect();
+      // Account for sub pixel differences from rounding
+      if ((Math.abs(originalLeft - newLeft) > 1) || (Math.abs(originalTop - newTop) > 1)) {
+        scrollParents = containingElement ? getScrollParents(containingElement, true) : [];
+        for (let scrollParent of scrollParents) {
+          scrollIntoView(scrollParent as HTMLElement, containingElement as HTMLElement, {block: 'center', inline: 'center'});
+        }
+      }


Since we added the bypass for chrome, this now also supports alternative alignments, to center the containingElement. This was missing in the previous PR also 👍

@nwidynski still in the middle of looking at the code, but I tested against the story that https://github.com/adobe/react-spectrum/pull/7717/changes#diff-b741e806d7e03bb7f42427dbe388c23128044ae2c96c612a9bceb9852ec408ab added and it seems to cause some strange scroll behaviors when attempting to use ArrowDown) to scroll an out of view item into view (for instance, Item 20 in that story). It seems to be hitting the last bit of logic in https://github.com/nwidynski/react-spectrum/blob/fc0f5a0fb1c2e15fd9d2d82a67b39feb0d350a89/packages/%40react-aria/utils/src/scrollIntoView.ts#L150, and attempts to scroll the item with respect to the gridlist itself which isn't actually scrollable itself in this story example. Rather, the wrapping div around the gridlist itself is scrollable here so theoretically we should've skipped the gridlist in favor of scrolling of scrolling the item against the wrapping div.

hmm, I suppose in that particular story, the scrollRef of the gridlist is inaccurate because of this wrapping div configuration (should be the wrapping div), perhaps we should allow configuring that...

That's been suggested as well #3489
Also related #3965

thanks for finding those issues. Its a bit unfortunate that without being able to set the scrollRef that this PR's change breaks the above use case, even though it had only worked previously by happenstance (aka we only called scrollIntoView once rather than accounting for the sub-pixel rounding).

nwidynski · 2025-11-04T23:51:17Z

packages/@react-aria/utils/src/scrollIntoView.ts

-      if (!isScrollPrevented) {
-        scrollParents.push(root);
-      }
+      let scrollParents = getScrollParents(targetElement, true);


Just noting that this does not behave like the native equivalent, since it skips overflow:hidden scroll parents. This potential issue also existed before this PR, so I don't think it's a blocker.

nwidynski · 2025-11-05T00:30:32Z

packages/@react-aria/utils/src/scrollIntoView.ts

+  if (shouldScrollBlock && block === 'start') {
+    y += scrollAreaLeft - scrollPortLeft;
+  } else if (shouldScrollBlock && block === 'center') {
+    y += (scrollAreaTop + scrollAreaBottom) / 2 - (scrollPortTop + scrollPortBottom) / 2;
+  } else if (shouldScrollBlock && block === 'end') {


Native scrollIntoView only checks for shouldScroll with the nearest alignment option. Should we also do that?

I think we can keep this as is, IMO this utility doesn't need to mirror the native behavior and I think we'd prefer more of a scrollIntoViewIfNeeded behavior anyways. Any concerns or thoughts from your end?

Hm, I'm not sure whether this is a public utility or internal. If it's public I think we should aim for closer parity, but provide an option to opt-in or out of IfNeeded behavior. One other issue where this is also not pairing the native version is that intermediate scrollParents below the scrollView also do not get scrolled. I think it would make sense to push the scrollParents loop into scrollIntoView to also align there.

honestly I'd classify this more of an internal utility (and thus can be more opinionated) since we never documented it for external usage, but it is a bit of a gray area. Making it a public utility and adding an option for IfNeeded would be nice, but it comes with the extra baggage of committing it to being public API and possibly increasing scope/maintenance depending on how much we'd want it to behave like native (as well as maintain behavior with native if that changes). Happy for the rest of the team to weigh in.

LFDanLu

Did some preliminary testing and the behavior looks good to me, thanks for the fix! I still need to sit down and go through all the math still haha, but I'll see about getting this into our upcoming test session so we can put it through its paces. Just to share timelines, the team is limited on bandwidth due to some pushes on some end of year docs work so realistically we may not get this in till the new year (which might be when the next release is anyways). Thanks once again for the through fix!

nwidynski · 2025-11-05T20:50:26Z

@LFDanLu No problem, i figure that implies the same for the pending review of the ScrollView refactor? At least I won't have much to maintain as long as focus largely remains on docs, haha. You would do me much more of a favor with preliminary feedback to the Carousel RFC, so I could come strong out the gate for the new year with a draft PR ready :)

Carousel's implementation is really quite a lot and I would love to avoid losing most of the detailed implementation insights i currently still got in short term memory 😅

LFDanLu · 2025-11-05T21:38:47Z

@nwidynski That's right, the team is currently focused on new docs + getting S2 out of pre-release so we don't have many spare cycles. Thank you for letting me know the Carousel RFC is a higher priority, I'll see if I can get at least a preliminary review by the team squeezed in.

nwidynski · 2025-12-02T23:04:29Z

packages/@react-aria/utils/src/scrollIntoView.ts

+  let viewTop = scrollView === root ? 0 : view.top;
+  let viewBottom = scrollView === root ? scrollView.clientHeight : view.bottom;
+  let viewLeft = scrollView === root ? 0 : view.left;
+  let viewRight = scrollView === root ? scrollView.clientWidth : view.right;


@snowystinger Related to https://github.com/adobe/react-spectrum/pull/7717/files#r1999951343, let me know if we need support for pinch-zoom here.

nwidynski · 2026-01-13T01:04:51Z

Just wanted to give this a bump so it doesn't get lost. Excuse me if you guys are not back to being fully staffed yet 😅

LFDanLu · 2026-02-03T23:22:56Z

I'll see about picking this back up soon hopefully, we ran into something similar via #7717

LFDanLu

wip review

LFDanLu · 2026-02-04T23:32:14Z

packages/@react-aria/utils/src/getScrollParents.ts

-  while (node && node !== document.documentElement) {
+  do {


noticed that with this change that if checkForOverflow is false, we'd return the root element as one of the scroll parentElements, even if the node provided is the root element. I don't think that case happens right now of in the code since I think we always check for overflow, but was curious what prompted this

I'm not sure I can follow why that is just the case for checkForOverflow=false, since the intention, iirc, was for it to always be included. We pass true in scrollIntoView solely as a runtime optimization to skip unscrollable parent elements, not out of necessity.

Basically all of what this changeset aims to do, is to move the scrollParents.push(root) of scrollIntoView into this helper method. I felt like this is the more appropriate place, in case somebody starts using this helper elsewhere - same goes for isScrollable which previously didn't work for the root element.

My initial hang up on was that it might be unexpected if someone was previously using this util and didn't expect root elements to be included (though to be fair we never documented this util and I would consider it as an internal util). From what I can tell, I think the original utility and scrollIntoView logic actually didn't want to include the root since it was only handling the overlay case where we had prevented scrolling from happening on the body anyways but with the changes in the PR that assumption no longer holds up so this is probably fine on second thought.

LFDanLu · 2026-02-04T23:58:59Z

packages/@react-aria/utils/src/scrollIntoView.ts

+      let {left: newLeft, top: newTop} = targetElement.getBoundingClientRect();
+      // Account for sub pixel differences from rounding
+      if ((Math.abs(originalLeft - newLeft) > 1) || (Math.abs(originalTop - newTop) > 1)) {
+        scrollParents = containingElement ? getScrollParents(containingElement, true) : [];
+        for (let scrollParent of scrollParents) {
+          scrollIntoView(scrollParent as HTMLElement, containingElement as HTMLElement, {block: 'center', inline: 'center'});
+        }
+      }


@nwidynski still in the middle of looking at the code, but I tested against the story that https://github.com/adobe/react-spectrum/pull/7717/changes#diff-b741e806d7e03bb7f42427dbe388c23128044ae2c96c612a9bceb9852ec408ab added and it seems to cause some strange scroll behaviors when attempting to use ArrowDown) to scroll an out of view item into view (for instance, Item 20 in that story). It seems to be hitting the last bit of logic in https://github.com/nwidynski/react-spectrum/blob/fc0f5a0fb1c2e15fd9d2d82a67b39feb0d350a89/packages/%40react-aria/utils/src/scrollIntoView.ts#L150, and attempts to scroll the item with respect to the gridlist itself which isn't actually scrollable itself in this story example. Rather, the wrapping div around the gridlist itself is scrollable here so theoretically we should've skipped the gridlist in favor of scrolling of scrolling the item against the wrapping div.

LFDanLu · 2026-02-05T00:07:05Z

packages/@react-aria/utils/src/scrollIntoView.ts

out of curiosity were these calculations based off any existing work? (math is hard, and this kind of code always has small pitfalls/non-obvious considerations that reminds me of the grueling overlay positioning code where I always have to start drawing diagrams and what not)

Most of it was honestly based on first principle thinking, which was done within the exploration and prep work for the Carousel RFC. Since ScrollDelegate operates within the constraints of the LayoutDelegate interface, and especially with my work on #8696, I already had to come up with the math anyways - and I was already drawing diagrams too 😅

This is why I suggested in that RFC review of yours, that deeper integration might be able to replace scrollIntoView. Looking at the library, which Rob linked in https://github.com/adobe/react-spectrum/pull/7717/changes#r1999951343, I think the calculations largely appear very similar.

LFDanLu

will have to discuss https://github.com/adobe/react-spectrum/pull/9146/changes#r2766507693 with the team since although technically not supported, the scrollable wrapping div case did happen to "work" previously. Otherwise the logic looks good, will see if we can do some more testing in next weeks testing sesion

packages/@react-aria/utils/src/scrollIntoView.ts

Co-authored-by: Daniel Lu <danilu@adobe.com>

…lintoviewport

LFDanLu

Applied a fix for something we noticed in testing (didn't account for scrollbars) but otherwise looks good! Sorry about the delay

nwidynski · 2026-02-10T12:21:14Z

@LFDanLu Thanks for noticing that. I could've sworn to have thought about scrollbar dimensions like 10 times while implementing this, haha. In any way, I've followed up in #9634 since that fix would have broken down in some edge cases.

feat: refactor scrollintoview

7a4d510

nwidynski mentioned this pull request Nov 4, 2025

scrollIntoView should account for scroll-margin of element #8689

Closed

nwidynski commented Nov 4, 2025

View reviewed changes

nwidynski commented Nov 5, 2025

View reviewed changes

LFDanLu reviewed Nov 5, 2025

View reviewed changes

fix: typo

fc0f5a0

nwidynski mentioned this pull request Nov 21, 2025

chore: Carousel or Image Rotator RFC #9084

Open

5 tasks

nwidynski commented Dec 2, 2025

View reviewed changes

nwidynski mentioned this pull request Feb 3, 2026

fix: offset calculation to handle transformed elements with translateY or translateX in scrollIntoView #7717

Merged

5 tasks

LFDanLu reviewed Feb 5, 2026

View reviewed changes

LFDanLu reviewed Feb 7, 2026

View reviewed changes

packages/@react-aria/utils/src/scrollIntoView.ts Outdated Show resolved Hide resolved

nwidynski and others added 3 commits February 7, 2026 14:20

chore: review suggestions

0e8ce94

Co-authored-by: Daniel Lu <danilu@adobe.com>

Merge branch 'main' of github.com:adobe/react-spectrum into fix-scrol…

1215931

…lintoviewport

accomodate for scrollbars

160d376

snowystinger approved these changes Feb 10, 2026

View reviewed changes

LFDanLu approved these changes Feb 10, 2026

View reviewed changes

LFDanLu added this pull request to the merge queue Feb 10, 2026

Merged via the queue into adobe:main with commit fd9e5f6 Feb 10, 2026
27 checks passed

nwidynski mentioned this pull request Feb 10, 2026

fix: scrollIntoView scrollbar width & rtl layout support #9634

Merged

5 tasks

Conversation

nwidynski commented Nov 4, 2025

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

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!

nwidynski Nov 5, 2025 • 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!

nwidynski Nov 5, 2025 • 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!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

nwidynski commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LFDanLu commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

LFDanLu commented Feb 3, 2026

Uh oh!

LFDanLu left a comment

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!

nwidynski Feb 5, 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!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nwidynski commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

nwidynski Nov 5, 2025 •

edited

Loading

nwidynski Nov 5, 2025 •

edited

Loading

nwidynski commented Nov 5, 2025 •

edited

Loading

LFDanLu commented Nov 5, 2025 •

edited

Loading

nwidynski commented Jan 13, 2026 •

edited

Loading

nwidynski Feb 5, 2026 •

edited

Loading

nwidynski commented Feb 10, 2026 •

edited

Loading