Skip to content
Source
Sign inSign up
TanStack/virtual

fix(virtual-core): let a user scroll end a non-smooth scrollToIndex before it lands #1310

Mergedpiecykmerged 2 commits intomain fromrefs/pull/1310/headmerged by piecyk

piecykcommented

Stacked on #1309. This branch contains #1309's commit; review only the last commit, fix(virtual-core): let a user scroll end a non-smooth scrollToIndex before it lands. I'll rebase and mark it ready once #1309 merges.

🎯 Changes

The scroll handler treated a scroll event as the user leaving an index scroll only after reconcile had seen the target reached. When the target keeps moving while rows are measured (or, on iOS, when a write is ignored under a finger) the scroll never "reaches" it, so the state stays alive after the user scrolls away, and the next measurement that moves the target writes them back to it. Reproduced on desktop and on iOS in #1307; pinned by two test.fails in #1308.

 scroll event that isn't the read-back of our own write
   if index scroll
-     && hasReachedTarget
+     && (hasReachedTarget || !startedSmooth)
      && offset not ≈ lastTargetOffset and not ≈ fresh target
      && not a clamped compensation read-back
     end the index scroll

 ScrollState
+  startedSmooth  // set when the command starts; `behavior` is switched to
+                 // 'auto' by reconcile for the final approach
  • Non-smooth: the write lands at once, so any other event is the user's.
  • Clamped writes (#1294): a read-back short of what we wrote because the scroll max shrank reports the max, where the fresh target also clamps, so the existing "≈ fresh target" check keeps it reconciling. Clamped compensation writes stay covered by _clampedAdjustment.
  • Smooth: unchanged. Animation events look like a user's, so a smooth scroll still yields only after reaching its target. Decided by startedSmooth rather than behavior, because WebKit can deliver animation events after reconcile's switch to 'auto'.

Evidence

Casebeforeafter
#1308 "a drag that never reached the target is not pulled back when the target moves" (iOS, write ignored under a finger)2550 (pulled back)60
#1308 "a scroll away from a target that moved before landing is not pulled back, non-iOS"26001050
Smooth scrollToIndex switched to 'auto' near the end, then a late animation eventkeptkept (new test; fails if the check uses behavior)
#1294 clamp: read-back at a shrunken max before the target is reachedkeptkept
  • virtual-core: 233 passed + 5 expected failures (remaining #1307 iOS cases). Mutation check: every part of the condition is covered.
  • react-virtual cached-measurements, smooth-scroll, smooth-prepend, scroll in Chromium, Firefox and WebKit: all pass. WebKit A/B against the parent, 4 runs each interleaved: 0 vs 0 failures (checking behavior instead of startedSmooth gave 8 failures).
  • react-virtual e2e 39/39; Marko chat "does NOT follow appends while reading history" 10/10; pnpm run test:pr green.

Merge Danger

Door: two-way. One condition in the scroll handler plus a flag set where scroll commands start.

Blast Radius: non-smooth scrollToIndex / scrollToEnd while they haven't been seen to land. A user scroll (wheel inertia included) now ends them immediately instead of being pulled back by the next measurement, which matches native scrollIntoView. A non-user event in that window that is neither our read-back nor at the target would now end the scroll too; a differential sweep over 98 scenarios (align, lanes, gap, paddings, scroll paddings, scrollMargin, horizontal, window scroller, custom adjust predicate, anchorTo: 'end', rAF-deferred ResizeObserver, iOS) found none.

Known and unchanged: a prepend (anchorTo: 'end') committing before an index write's read-back still loses the scroll (on main it was stranded, then pulled back later). Tracked with the other shared stalls in #1307.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes
    • User-initiated scrolling no longer gets pulled back to an outdated scrollToIndex target when a non-smooth scroll is interrupted before reaching it.
    • Improved handling of browser-clamped scroll targets and late scroll events.
    1. 🦋 Changeset detected

      Latest commit: f596cb0bfc0633a2d236134b715300372f1073a3

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 9 packages
      NameType
      @tanstack/virtual-corePatch
      @tanstack/angular-virtualPatch
      @tanstack/lit-virtualPatch
      @tanstack/marko-virtualPatch
      @tanstack/react-virtualPatch
      @tanstack/solid-virtualPatch
      @tanstack/svelte-virtualPatch
      @tanstack/vue-virtualPatch
      @tanstack/virtual-benchmarksPatch

      Not sure what this means? Click here to learn what changesets are.

      Click here if you're a maintainer who wants to add another changeset to this PR

    2. Review in Change Stack →

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration
      • Configuration used: defaults
      • Review profile: CHILL
      • Plan: Advanced
      • Run ID: 1126db8d-b0ec-40be-b260-b97df1676390

      📥 Commits

      Reviewing files that changed from the base of the PR and between e7a0a92e4bec5ecd0a37659e951c8e8ff72e0207 and f596cb0bfc0633a2d236134b715300372f1073a3.


      📒 Files selected for processing (3)
      • .changeset/index-scroll-user-interrupt.md
      • packages/virtual-core/src/index.ts
      • packages/virtual-core/tests/index.test.ts

      Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 5 remain after this review.



      📝 Walkthrough

      Walkthrough

      Scroll commands now record whether they began with smooth behavior. Index-scroll reconciliation uses that state to distinguish non-smooth interruptions from smooth-scroll events. Tests cover user scrolling, late events, and writes clamped by a shrinking sizer.

      Changes

      Index Scroll Interruption

      Layer / File(s)Summary
      Scroll behavior and reconciliation
      packages/virtual-core/src/index.ts, packages/virtual-core/tests/index.test.ts, .changeset/index-scroll-user-interrupt.md
      Scroll commands record whether they started with smooth behavior. Reconciliation can cancel a non-smooth index scroll before it reaches its target. Tests cover user interruptions, late smooth-scroll events, and a clamped write; the changeset describes the fix.

      Priority: ⬇️ Low

      Estimated code review effort: 2 (Simple) | ~15 minutes

      Change: Bug fix


      Merge Risk: 🔵 Low · up to f596c

      The user-scroll interruption fix is mergeable with awareness that an unobserved clamped-scroll ordering could leave a requested row off-target.

      Pre-merge checks | Passed 5
      ✅ Passed checks (5 passed)
      Check nameStatusExplanation
      Title checkPassedThe title clearly and concisely identifies the main change: allowing user scrolling to end a non-smooth scrollToIndex before it reaches its target.
      Description checkPassedThe description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, implementation, testing evidence, release impact, and known limitations. Both checkli…
      Docstring CoveragePassedDocstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 …
      Linked Issues checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck skipped because no linked issues were found for this pull request.

      ✨ Finishing Touches
      🧪 Generate unit tests (beta)
      • Create a new PR

      • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      Warning

      Some tools did not complete. Review the errors below.

      🔧 ESLint

      If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

      packages/virtual-core/tests/index.test.ts

      Parsing error: "parserOptions.project" has been provided for @typescript-eslint/parser. The file was not found in any of the provided project(s): packages/virtual-core/tests/index.test.ts



      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share

      Comment `@coderabbitai help` to get the list of available commands.
    3. View your CI Pipeline Execution ↗ for commit e29a0223a9342261b68c543ea15cfd2d46cf43b7

      CommandStatusDurationResult
      nx affected --targets=test:sherif,test:knip,tes...✅ Succeeded4m 7sView ↗
      nx run-many --target=build --exclude=examples/**✅ Succeeded14sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-10-12 10:42:06 UTC

    4. More templates

      @tanstack/angular-virtual

      npm i https://pkg.pr.new/@tanstack/angular-virtual@1310

      @tanstack/lit-virtual

      npm i https://pkg.pr.new/@tanstack/lit-virtual@1310

      @tanstack/marko-virtual

      npm i https://pkg.pr.new/@tanstack/marko-virtual@1310

      @tanstack/react-virtual

      npm i https://pkg.pr.new/@tanstack/react-virtual@1310

      @tanstack/solid-virtual

      npm i https://pkg.pr.new/@tanstack/solid-virtual@1310

      @tanstack/svelte-virtual

      npm i https://pkg.pr.new/@tanstack/svelte-virtual@1310

      @tanstack/virtual-core

      npm i https://pkg.pr.new/@tanstack/virtual-core@1310

      @tanstack/vue-virtual

      npm i https://pkg.pr.new/@tanstack/vue-virtual@1310

      commit: f596cb0

    5. Reviewed the last commit at 2b7ac8b4. The fix works in real browsers, I found no regression, and it also removes a flake in the Chromium chat spec.

      The fix, in real browsers. Plain-DOM list on virtual-core, 1000 rows estimated at 50px and measuring 50–109px. scrollToIndex(500, { align: 'start' }), then scrollTop -= 300. Same numbers in Chromium, Firefox and WebKit:

      user scroll one frame lateruser scroll in the same task
      main, #1309pulled back, row 500 at the toppulled back, row 500 at the top
      this PRstays, moved only by the 110px of size correctionsstays, moved only by 115px of corrections

      It fixes the chat.spec.ts flake. react-virtual e2e, Chromium, 40 repetitions per revision in interleaved blocks of 10, --retries=0:

      Testmain#1309this PR#1311
      keeps visible messages stable when history is prepended18/4019/4040/4040/40
      does not follow appended messages while reading history29/4037/4040/4040/40

      The first one is the chat.spec.ts:73 timeout I reported in #1308.

      No landing regression. The 34,200 uninterrupted index scrolls from my #1309 comment land identically on #1309 and on this PR. The only difference is that 54 runs that sat off-target until the 5s safety valve on #1309 now retire at the next scroll-rest event, at the same position.

      Mutation check. Checking behavior instead of startedSmooth, reverting to hasReachedTarget only, and always yielding each fail the tests you would expect. Dropping the lastTargetOffset comparison (not new in this PR) fails nothing.

      Two questions, neither a blocker as far as I could measure:

      1. A scrollToFn that does not land in the same task, like the docs' smooth-scroll example (rAF easing, scrollToIndex with the default behavior). Its first intermediate scroll event is neither the read-back nor at the target, so the index scroll now ends on the first animation frame instead of living until it lands. With fixed rows the landing is the same (row 500 at 0 on all revisions, Chromium). With dynamic rows that pattern is already broken on main (row 500 about 20,700px away after 9s, about 22,000px here), so I cannot call it a regression. But startedSmooth only knows about behavior: 'smooth', and a custom scrollToFn is the other way a write can travel. Is that a case you want to keep alive, or is it out of scope?

      2. A clamped read-back while the fresh target is below the new max. The comment says the read-back at the max "is also where the fresh target clamps". That does not hold if rows above the target shrink in the same window. Simulated: 100 rows of 50px, scrollToIndex(90, { align: 'start' }) writes 4500, rows 0–19 measure at 20px before the read-back, the max drops to 4200 and the target to 3900. main lands on 3900; this PR stops at 4200 with row 90 300px above the viewport. I could not produce that ordering in a real browser or anywhere in the sweep, so it may be unreachable in practice. Flagging it because the comment reads as if it cannot happen.

      WebKit smooth-scroll and smooth-prepend are flaky on my machine on every revision including main, at similar rates (numbers in #1307). I did not reproduce the 0 vs 0 from your A/B, but nothing there points at this PR.

    6. @phcorp thanks for review! Regarding clamped read-back below a shrunk target: you're right that the comment overstated it. I reproduced your numbers in core (4200 instead of 3900). It only happens if the re-render that shrinks the sizer runs before the scroll event; without a render the stale target clamps to the read-back and reconciling carries on. Since it has never been seen in a browser, I pinned it with a .fails test and corrected the comment (f596cb0b) rather than adding a special case to the scroll handler. If it shows up for real, that test is the starting point.

    7. piecyk merged this7aa34f6

    8. piecyk closed this

Sign in to join this conversation.