fix: scroll anchoring improvements for chat by yihuiliao · Pull Request #10600 · adobe/react-spectrum

yihuiliao · 2026-09-11T23:21:24Z

This PR fixes a couple of things. Some of which were from testing in July and some that were noticed while making the ai component docs.

Updates the width of the Chat in storybook so it fits on mobile screens
Removes unneeded state to calculate scroll anchoring (see devon's comment)
Fixes the scroll positioning from jumping on mobile
Expanding and collapsing response status in virtualized chat thread has weird scroll behavior (like it is opening upward).

For 2, I removed the hadEstimatedVisibleItems / wasNearAnchorEdge fields that tried to remember "are we near the edge?" across a resize. They were redundant since resolveScrollAdjustment already gets itemSizeChanged and contentSizeDelta per pass, so the same decision (follow edge vs. keep anchor) can be made directly from those without tracked history.

For 3, scroll position jumped on mobile, an item can only be anchored if it fits fully inside the viewport. On mobile, one tall item can fill the whole screen, so nothing ever fully fit and no anchor was picked. Now we anchor to the item closest to the edge even if it's partly cut off, falling back to the least-cut-off item if none fit.

For 4, expanding/collapsing response status scrolled upward instead of staying put, a resize anywhere in the list was treated as if it happened at the anchored edge when the chat was short, so the virtualizer would "follow the edge" and snap the scroll position, even when the resized item was in the middle of the list. Added tracking for whether a resize batch actually touched the newest item; if it didn't, we preserve the user's reading position instead of following the edge.

✅ 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
I understand every change in this PR and can explain why it's there.
If AI-assisted, I followed our AI contribution guidance and pointed my assistant at CLAUDE.md.

📝 Test Instructions:

🧢 Your Project:

rspbot · 2026-09-11T23:27:40Z

Build successful! 🎉

…iner

rspbot · 2026-09-30T23:34:34Z

Build successful! 🎉

rspbot · 2026-10-03T01:11:28Z

Build successful! 🎉

rspbot · 2026-10-05T19:37:23Z

Build successful! 🎉

rspbot · 2026-10-05T19:39:49Z

Build successful! 🎉

yihuiliao · 2026-10-08T17:27:40Z

+    // Decide whether the change that triggered this relayout was at the anchored edge. If items
+    // resized but none of them were the newest content, we don't follow the edge and we keep the
+    // user's reading position instead.
+    let changeIsAtEdge = !this._hadItemResize || this._batchIncludedEdgeContent;


If only older messages resized, preserve the reading position instead of following the bottom. If the resize batch includes newest content, bottom-following remains eligible (but not a guarantee. there are other conditions that need to be met for the bottom-following to happen).

This is for the case where the chat is quite short, meaning that an older message is still within the threshold of being considered "near bottom".

yihuiliao · 2026-10-08T17:27:54Z

+    // (scrolling, a new message, a window resize). If we left the flags set, the next relayout
+    // would still see this pass's "an item resized / it was at the edge" values and make the wrong call.
+    this._hadItemResize = false;
+    this._batchIncludedEdgeContent = false;


Clear the resize flags after each relayout so the next pass doesn’t reuse this batch’s classification.

yihuiliao · 2026-10-08T17:28:18Z

    if (changed) {
+      this._hadItemResize = true;
+      // "Batch" refers to the set of updateItemSize calls that happen between one relayout and the next
+      this._batchIncludedEdgeContent ||= this.isEdgeContent(key);


Several items can measure before one relayout. Remember whether any changed item was edge content which is decided in ListLayout. In this case, if it's the last item (and not a loader), it counts as edge content.

yihuiliao · 2026-10-08T17:29:02Z

+        : 'topRight'
+      : edge === 'end'
+        ? 'topLeft'
+        : 'bottomLeft';


For bottom anchoring, track the item’s top so resizing the item itself doesn’t move our reference point. Top anchoring uses the item’s bottom; horizontal layouts use the equivalent left/right edges.

yihuiliao · 2026-10-08T17:29:25Z

    }
  }
-  return best;
+  return best ?? fallback;


Prefer an item whose top is visible. Only fall back to a clipped item when no visible-top candidate exists.

yihuiliao · 2026-10-08T17:35:29Z

  let domProps = filterDOMProps(otherProps);
  let {isFocusVisible, focusProps} = useFocusRing();
  let hasDetail = detail != null;
+  // Play the entrance (fade + slide) once, then remove the animating styles.


You can reproduce this on our current docs. Go to the AI components page, go to the Chat Threads example, open the ResponseStatus and the ExecutionTrace items, and then scroll up and down. You should see a brief flash and then the contents settle in again.

If you open DevTools > More Tools > Rendering > Layer borders, you should see the layer appear and disappear.

This is what I (and claude) ended up coming up with but if anyone has better ideas, let me know. Can't say this whole browser layer stuff is my strong suite.

yihuiliao · 2026-10-08T17:45:48Z

This is the framework of what the scroll anchoring captures in a couple of different use cases. This is what I have for now, I think they're subject to change as we test this more.

Visible items Selected anchor

One or more items with visible tops The one whose top is nearest the viewport top.

Top-clipped item plus another with a visible top Prefer the visible-top item

Only top-clipped candidates Use the least-clipped candidate’s actual top, with a negative offset.

Item’s top visible, bottom clipped Still a preferred candidate; full visibility isn’t required.

yihuiliao · 2026-10-08T22:17:06Z

-    // and following it would fall short of the edge.
-    let effectiveAnchor =
-      isFirstAnchoredLayout || (wasSettlingLastPass && wasNearAnchorEdgeLastPass) ? null : anchor;
+    let effectiveAnchor = isFirstAnchoredLayout ? null : anchor;


So previously, wasSettlingLastPass and wasNearAnchorEdgeLastPass remembered whether we were near the bottom while estimated items were measuring, and used that to skip item-anchor preservation on later passes. But being near the bottom when items are measuring doesn't mean we should be pulled to the bottom. For example, opening older content should preserve the reading position.

Now, bottom-anchoring is decided separately using proximity and whether the resize batch includes edge content (along with other conditions). Older-item-only resizes no longer trigger a bottom snap just because we’re within the threshold.

rspbot · 2026-10-08T23:07:30Z

Build successful! 🎉

rspbot · 2026-10-08T23:07:31Z

## API Changes

@react-aria/utils

/@react-aria/utils:isKeyboardOpen

+isKeyboardOpen {
+  returnVal: undefined
+}

/@react-aria/utils:supportsKeyboard

+supportsKeyboard {
+  returnVal: undefined
+}

@react-spectrum/s2

/@react-spectrum/s2:SideNavItem

 SideNavItem {
   aria-label?: string
   children: ReactNode
   download?: boolean | string
-  focusMode?: 'child' | 'row' = 'row'
   hasChildItems?: boolean
   href?: Href
   hrefLang?: string
   id?: Key
   onHoverChange?: (boolean) => void
   onHoverEnd?: (HoverEvent) => void
   onHoverStart?: (HoverEvent) => void
   onPress?: (PressEvent) => void
   onPressChange?: (boolean) => void
   onPressEnd?: (PressEvent) => void
   onPressStart?: (PressEvent) => void
   onPressUp?: (PressEvent) => void
   ping?: string
   referrerPolicy?: HTMLAttributeReferrerPolicy
   rel?: string
   routerOptions?: RouterOptions
   target?: HTMLAttributeAnchorTarget
   textValue: string
 }

/@react-spectrum/s2:SideNavPanel

-SideNavPanel {
-  UNSAFE_className?: UnsafeClassName
-  UNSAFE_style?: CSSProperties
-  aria-describedby?: string
-  aria-details?: string
-  aria-label?: string
-  aria-labelledby?: string
-  children?: ReactNode
-  defaultCollapsed?: boolean
-  isCollapsed?: boolean
-  onCollapsedChange?: (boolean) => void
-  styles?: StylesPropWithHeight
-}

/@react-spectrum/s2:SideNavPanelContext

-SideNavPanelContext {
-  UNTYPED
-}

/@react-spectrum/s2:SideNavItemProps

 SideNavItemProps {
   aria-label?: string
   children: ReactNode
   download?: boolean | string
-  focusMode?: 'child' | 'row' = 'row'
   hasChildItems?: boolean
   href?: Href
   hrefLang?: string
   id?: Key
   onHoverChange?: (boolean) => void
   onHoverEnd?: (HoverEvent) => void
   onHoverStart?: (HoverEvent) => void
   onPress?: (PressEvent) => void
   onPressChange?: (boolean) => void
   onPressEnd?: (PressEvent) => void
   onPressStart?: (PressEvent) => void
   onPressUp?: (PressEvent) => void
   ping?: string
   referrerPolicy?: HTMLAttributeReferrerPolicy
   rel?: string
   routerOptions?: RouterOptions
   target?: HTMLAttributeAnchorTarget
   textValue: string
 }

/@react-spectrum/s2:SideNavPanelProps

-SideNavPanelProps {
-  UNSAFE_className?: UnsafeClassName
-  UNSAFE_style?: CSSProperties
-  aria-describedby?: string
-  aria-details?: string
-  aria-label?: string
-  aria-labelledby?: string
-  children?: ReactNode
-  defaultCollapsed?: boolean
-  isCollapsed?: boolean
-  onCollapsedChange?: (boolean) => void
-  styles?: StylesPropWithHeight
-}

/@react-spectrum/s2:SidePanel

+SidePanel {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode
+  defaultCollapsed?: boolean
+  isCollapsed?: boolean
+  onCollapsedChange?: (boolean) => void
+  styles?: StylesPropWithHeight
+}

/@react-spectrum/s2:SidePanelContext

+SidePanelContext {
+  UNTYPED
+}

/@react-spectrum/s2:SidePanelProps

+SidePanelProps {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode
+  defaultCollapsed?: boolean
+  isCollapsed?: boolean
+  onCollapsedChange?: (boolean) => void
+  styles?: StylesPropWithHeight
+}

rspbot · 2026-10-08T23:07:33Z

Agent Skills Changes

Added (1)

s2/agent-skills/react-spectrum-s2/references/components/SidePanel.md $\color{green}{+284}$

Removed (1)

s2/agent-skills/react-spectrum-s2/references/components/SideNavPanel.md

Modified (16)

react-aria/agent-skills/index.json $\color{green}{+1}$ $\color{red}{-1}$
react-aria/agent-skills/react-aria.tar.gz
react-aria/agent-skills/react-aria/references/components/Separator/useSeparator.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/agent-skills/react-aria/references/components/Sheet.md $\color{green}{+6}$ $\color{red}{-31}$
react-aria/agent-skills/react-aria/references/llms.txt $\color{red}{-2}$
s2/agent-skills/index.json $\color{green}{+3}$ $\color{red}{-3}$
s2/agent-skills/migrate-react-spectrum-v3-to-s2.tar.gz
s2/agent-skills/react-spectrum-s2.tar.gz
s2/agent-skills/react-spectrum-s2/SKILL.md $\color{green}{+1}$ $\color{red}{-1}$
s2/agent-skills/react-spectrum-s2/references/components/SideNav.md $\color{red}{-1}$
s2/agent-skills/react-spectrum-s2/references/guides/ai-components.md $\color{green}{+4}$ $\color{red}{-24}$
s2/agent-skills/react-spectrum-s2/references/llms.txt $\color{green}{+1}$ $\color{red}{-2}$
s2/agent-skills/react-spectrum-s2/references/react-aria/components/Separator/useSeparator.md $\color{green}{+1}$ $\color{red}{-1}$
s2/agent-skills/react-spectrum-s2/references/react-aria/components/Sheet.md $\color{green}{+6}$ $\color{red}{-31}$
s2/agent-skills/react-spectrum-s2/references/react-aria/llms.txt $\color{red}{-2}$
s2/agent-skills/spectrum-audit.tar.gz

Install

React Spectrum S2:

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/6c3c9d109d0d4f29f0805a4faf6f0c00a5dce2e5/

React Aria:

npx skills add https://d5iwopk28bdhl.cloudfront.net/pr/6c3c9d109d0d4f29f0805a4faf6f0c00a5dce2e5/

yihuiliao · 2026-10-09T02:42:16Z

  }

-  if (wasNearAnchorEdge && !isScrolling && (!itemSizeChanged || contentSizeDelta > 0)) {
+  if (wasNearAnchorEdge && (!itemSizeChanged || contentSizeDelta !== 0) && changeIsAtEdge) {


Removing the isScrolling guard because it currently treats programmatic scroll adjustments the same as user scrolling. When ResponseStatus expands as the last item, a scroll adjustment can mark scrolling as active and block subsequent bottom-following, leaving execution items below the viewport.

However, removing this guard may pull users back towards the bottom during active scrolling but I've tested it myself and I don't think it's the worst...but it is a tradeoff.

As a follow-up, I think we may need to differentiate between programmatic scrolling vs. user scrolling.

yihuiliao added 7 commits July 27, 2026 20:19

remove extra states

2bd5e63

update width in story

8df9329

Merge branch 'main' into reverse-virtualizer-follow-up

0e4b817

fix scroll jumping on mobile

6699536

add tests

f1643ff

Merge branch 'main' into reverse-virtualizer-follow-up

5ef7ec9

fix scroll anchoring for when small chats resize

1fed441

yihuiliao added 2 commits September 16, 2026 14:04

comment updates

a446f95

fix execution trace from flashing when scrolling in virtualized conta…

dc70f50

…iner

github-actions Bot added ResponseStatus AI labels Sep 16, 2026

yihuiliao added 2 commits September 29, 2026 14:31

Merge branch 'main' into reverse-virtualizer-follow-up

28c197e

fix lint

1322ef4

yihuiliao mentioned this pull request Sep 30, 2026

fix: add scrollbar gutter to style macro #10682

Merged

7 tasks

yihuiliao added 3 commits September 30, 2026 13:43

Merge branch 'main' into reverse-virtualizer-follow-up

dc9e65c

fix flashing dividers in response status

3d24a76

cleanup

440c432

yihuiliao added 4 commits October 2, 2026 17:36

feedback from copilot

37e1472

refactor anchor to bottom code

e34ec0c

fix formatting

9fd9048

Merge branch 'main' into reverse-virtualizer-follow-up

3da2fbe

yihuiliao added 2 commits October 5, 2026 12:26

cleanup tests

27adf55

more cleanup

f9524b7

yihuiliao marked this pull request as ready for review October 5, 2026 23:36

yihuiliao changed the title ~~wip: scroll anchoring improvements for chat~~ fix: scroll anchoring improvements for chat Oct 5, 2026

yihuiliao added the ready for review label Oct 5, 2026

yihuiliao commented Oct 8, 2026

View reviewed changes

yihuiliao added 2 commits October 8, 2026 15:29

remove isScrolling bc it's not sufficient enough for now

cac9134

fix formatting

6c3c9d1

yihuiliao commented Oct 9, 2026

View reviewed changes

Visible items	Selected anchor
One or more items with visible tops	The one whose top is nearest the viewport top.
Top-clipped item plus another with a visible top	Prefer the visible-top item
Only top-clipped candidates	Use the least-clipped candidate’s actual top, with a negative offset.
Item’s top visible, bottom clipped	Still a preferred candidate; full visibility isn’t required.

Conversation

yihuiliao commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Sep 11, 2026

Uh oh!

rspbot commented Sep 30, 2026

Uh oh!

rspbot commented Oct 3, 2026

Uh oh!

rspbot commented Oct 5, 2026

Uh oh!

rspbot commented Oct 5, 2026

Uh oh!

yihuiliao Oct 8, 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!

yihuiliao Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

yihuiliao Oct 8, 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!

yihuiliao Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

yihuiliao Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

yihuiliao Oct 8, 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!

yihuiliao Oct 8, 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!

yihuiliao Oct 8, 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!

rspbot commented Oct 8, 2026

Uh oh!

rspbot commented Oct 8, 2026

@react-aria/utils

/@react-aria/utils:isKeyboardOpen

/@react-aria/utils:supportsKeyboard

@react-spectrum/s2

/@react-spectrum/s2:SideNavItem

/@react-spectrum/s2:SideNavPanel

/@react-spectrum/s2:SideNavPanelContext

/@react-spectrum/s2:SideNavItemProps

/@react-spectrum/s2:SideNavPanelProps

/@react-spectrum/s2:SidePanel

/@react-spectrum/s2:SidePanelContext

/@react-spectrum/s2:SidePanelProps

Uh oh!

rspbot commented Oct 8, 2026

Agent Skills Changes

Uh oh!

yihuiliao Oct 9, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

yihuiliao commented Sep 11, 2026 •

edited

Loading

yihuiliao Oct 8, 2026 •

edited

Loading

yihuiliao Oct 8, 2026 •

edited

Loading

yihuiliao Oct 8, 2026 •

edited

Loading

yihuiliao Oct 8, 2026 •

edited

Loading

yihuiliao Oct 8, 2026 •

edited

Loading

yihuiliao Oct 9, 2026 •

edited

Loading