@tanstack/virtual-core

Every stable release, newest first. Notes are quoted as the maintainers published them.

1. 3.19.5

   15 October 2026
   virtual-core: keep an instant scroll command clamped at a max the sizer committed outside a row resizeBefore an instant scroll command's write is reported, the browser can clamp it at a smaller scroll max that the sizer moves to without a row resize: an append or prepend, measure(), or a resize the sizer had not committed when the command was written. The virtualizer now also records the max at each commit, so such an event is read as its own clamped write and the command lands. A clamped write reported with isScrolling false is now written again too.

   Patch Changes

   • fix(virtual-core): keep an instant scroll command clamped at a max the sizer committed outside a row resize

     Before an instant scroll command's write is reported, the browser can clamp it at a smaller scroll max that the sizer moves to without a row resize: an append or prepend, measure(), or a resize the sizer had not committed when the command was written. The virtualizer now also records the max at each commit, so such an event is read as its own clamped write and the command lands. A clamped write reported with isScrolling false is now written again too.

   • fix(virtual-core): keep an instant scroll command when the browser clamps its write before rows grow back

     Rows measured right after an instant scrollToEnd() (or scrollToIndex) can first shrink the sizer below the written position and then grow it again in the same task. The browser clamps the write to the smaller max, and the scroll event reports that position. It was read as the user scrolling away, so the command was cancelled and the list stopped short of the end (a chat opened with estimateSize larger than its rows). The virtualizer now follows the scroll max through those measurements and reads such an event as its own clamped write, so the command retargets and lands at the end.

   • fix(virtual-core): scroll commands and corrections that stalled or were lost

     • On iOS 27 and later a scrollTop write no longer stops a fling but is overridden by it within a frame. A scrollToIndex, scrollToOffset or scrollToEnd issued during a fling now waits for the fling to end instead of being lost. The user taking over before then cancels it: a drag, a second flick, or a finger stopping the fling (iOS reports none of these with touch events while the fling runs). Corrections keep being held through the gesture as on every version.

     • scrollToOffset / scrollBy: a row above the viewport growing after the write's read-back moved the element off the fixed target, and the command kept reconciling until the 5s safety valve. The target now moves with the correction.

     • A prepend (anchorTo: 'end') before the read-back of a scroll command was anchored against the stale offset and written over the command. It is now left to reconcile, like a resize in that window.

     • A scroll event between the prepend's options change and the adapter's commit no longer loses the anchor (one blank frame when the element could not be written by commit time).

     • A command's write clamped by a sizer that shrank below it before the read-back no longer reads as a user scroll; the command reaches its fresh target.

   • fix(virtual-core): on iOS 27 and later, a scroll command issued during a fling takes effect at once

     A scrollToIndex, scrollToOffset or scrollToEnd issued during a fling waited for the fling to end, so a button outside the list (such as "jump to latest") did nothing until the list stopped. The command now stops the fling by hiding the scroll element's overflow for two frames, then restores the element's own inline value and writes. The user taking over before the write still cancels the command.

   • refactor(virtual-core): move the iOS touch gesture tracking into its own internal module. One fix along the way: changing the scroll element no longer carries over a pending iOS late-fling window, which could defer corrections on the new element for 150ms.

   • fix(virtual-core): on iOS, defer scroll corrections only for touch-driven scrolls (a finger down, or the momentum after it), so a programmatic landing like scrollToOffset compensates before paint instead of snapping later

   • fix(virtual-core): hold a scroll correction the element cannot take instead of writing it

     A prepend's anchor delta or an above-viewport size change that lands while a scrollTop write is impossible (iOS during a touch gesture or its momentum tail, any WebKit while the element is rubber-banding past an edge) is now held: scrollOffset carries the corrected position, the rows and the total size are exposed shifted back by the held amount so every adapter keeps the reader's row where it is, and one write moves the element once a write is possible. Before, the write was discarded during the bounce on desktop Safari (the bounce stalled with the new rows and a blank top on screen), and on iOS the new rows showed through the bounce and snapped back at the flush.

   • refactor(virtual-core): simplify the scroll-correction state (no behaviour change)

     • A scroll event is classified once (spurious re-emit, our own write's read-back, a clamped read-back or echo, or external) before the handler acts on it, a scroll command waiting for the iOS 27 momentum tail is a phase of its own, and the iOS touch gesture tracks a single moved flag.

     • scrollAdjustments is deprecated: a correction is folded into scrollOffset at once, so it is always 0. Read scrollOffset alone; the getter stays.

     • One edge case changes: corrections made while enabled: false used to accumulate, and a correction made after re-enabling but before the next update was added on top of them. They are no longer carried over.

2. 3.19.4

   13 October 2026
   virtual-core: with useAnimationFrameWithResizeObserver, request frames from the scroll element's window instead of the global one, and cancel frames still queued on cleanup, so a list rendered into another window does not stall while the opener is minimized or occluded

   Patch Changes

   • fix(virtual-core): with useAnimationFrameWithResizeObserver, request frames from the scroll element's window instead of the global one, and cancel frames still queued on cleanup, so a list rendered into another window does not stall while the opener is minimized or occluded

3. 3.19.3

   13 October 2026
   virtual-core: simplify the scroll-correction state: a scroll write is tracked until its read-back as one record, the iOS touch gesture as one record, the pending prepend anchor as a tagged record, and every scroll command starts through one entry point (no behaviour change, with two exceptions: a second touchend/touchcancel inside the post-touch grace window now restarts the window instead of leaving the first timer to end it early, and after the scroll element is swapped or the virtualizer disabled, a write to the old element is no longer matched to the new element's first scroll report). scrollAdjustments becomes a read-only getter with the same value (assigning to it is no longer supported).

   Patch Changes

   • refactor(virtual-core): simplify the scroll-correction state: a scroll write is tracked until its read-back as one record, the iOS touch gesture as one record, the pending prepend anchor as a tagged record, and every scroll command starts through one entry point (no behaviour change, with two exceptions: a second touchend/touchcancel inside the post-touch grace window now restarts the window instead of leaving the first timer to end it early, and after the scroll element is swapped or the virtualizer disabled, a write to the old element is no longer matched to the new element's first scroll report). scrollAdjustments becomes a read-only getter with the same value (assigning to it is no longer supported).

4. 3.19.2

   12 October 2026
   virtual-core: treat iOS touchcancel like touchend so interrupted gestures cannot leave touch state stuck and keep scroll anchoring suppressed

   Patch Changes

   • fix(virtual-core): treat iOS touchcancel like touchend so interrupted gestures cannot leave touch state stuck and keep scroll anchoring suppressed

   • refactor(virtual-core): track an in-flight scroll command's lifecycle as one phase instead of several flags (no behaviour change)

5. 3.19.1

   12 October 2026
   virtual-core: let a user scroll end a non-smooth scrollToIndex before reconcile has seen it land, so a later measurement no longer pulls the user back to the old target

   Patch Changes

   • fix(virtual-core): let a user scroll end a non-smooth scrollToIndex before reconcile has seen it land, so a later measurement no longer pulls the user back to the old target

   • fix(virtual-core): leave resizes measured before a scroll command's write is read back to reconcile, so an upward scrollToIndex no longer jumps back and stalls until the safety valve, and build scrollBy on a just-written offset

6. 3.19.0

   11 October 2026
   virtual-core: keep lanes aligned after changing lanes with measureElement

   Minor Changes

   • fix(virtual-core): keep lanes aligned after changing lanes with measureElement

     • overscan now counts whole rows when lanes > 1, so every lane renders (and measures) the same number of extra items. This renders more items than before: lanes: 4, overscan: 2 now adds 8 items on each side instead of 2. Range gains an optional lanes field that defaultRangeExtractor reads; a custom rangeExtractor gets row overscan only if it delegates to defaultRangeExtractor.

     • A ResizeObserver callback now measures all of its entries before notifying, so a synchronous re-render can no longer unmount part of a row before it is measured.

   Patch Changes

   • fix(virtual-core): don't replay iOS-deferred size corrections after an in-flight scrollToIndex lands

7. 3.18.0

   9 October 2026
   virtual-core: add cancelScroll() to stop an in-flight scrollToIndex / scrollToOffset / scrollBy / scrollToEnd from correcting toward its target, so a user gesture can take over the viewport

   Minor Changes

   • feat(virtual-core): add cancelScroll() to stop an in-flight scrollToIndex / scrollToOffset / scrollBy / scrollToEnd from correcting toward its target, so a user gesture can take over the viewport

   Patch Changes

   • Fix scrollToIndex(last, { align: 'end' }) overshooting the last item by paddingEnd; it now respects scrollPaddingEnd like other end-aligned items. To scroll to the very bottom including paddingEnd, use scrollToEnd().

   • fix(virtual-core): don't cache a 0 size when measureElement receives a node that isn't attached to the document yet

   • Keep scrollToIndex reconciliation active until pending ResizeObserver measurements can update its target, including when useAnimationFrameWithResizeObserver is enabled. Respect an external scroll away from a reached target during this settling period.

8. 3.17.11

   14 September 2026
   Read the current scroll offset when the debounced scroll-end fallback fires so measurement adjustments made since the last browser scroll event are not overwritten by stale state.

   Patch Changes

   • Read the current scroll offset when the debounced scroll-end fallback fires so measurement adjustments made since the last browser scroll event are not overwritten by stale state.

   • Keep a travelling smooth scrollToIndex alive when content is prepended. With anchorTo: 'end', the prepend anchor sync wrote scrollTop instantly, which cancelled the browser's smooth animation and left the scroll stranded partway; Chromium drops a smooth request re-issued right after such a cancel, so it could not be resumed. The sync is now skipped while a smooth programmatic scroll is still in flight, and the animation continues to its recomputed target. A smooth scroll that has already landed still receives the anchor sync.

9. 3.17.10

   11 September 2026
   Keep an end-pinned virtualizer following appended items when older items are trimmed in the same update and the item count does not increase. Recognize ordered, overlapping windows while preserving reading anchors for users who have scrolled away from the end.Preserve item keys in the lazy measurement cache so a stable getItemKey callback reading mutable data cannot change the identity of previously measured rows.

   Patch Changes

   • Keep an end-pinned virtualizer following appended items when older items are trimmed in the same update and the item count does not increase. Recognize ordered, overlapping windows while preserving reading anchors for users who have scrolled away from the end.

     Preserve item keys in the lazy measurement cache so a stable getItemKey callback reading mutable data cannot change the identity of previously measured rows.

10. 3.17.9

    7 September 2026
    Recover the bottom pin when the browser clamps an end-anchored scroll compensation write. resizeItem compensates a size change by writing scrollTop before the consumer has committed the new total size, so when the grown item does not itself extend the scroll range the browser clamps the write to the old maximum and the viewport is left short of the end with no scroll event to correct it. Two cases hit this: paddingEnd > 0 with a growing last item, where the overflowing item only extends scrollHeight to its own end and the clamp lands exactly paddingEnd short (#1258); and a row above the last one growing while the last row keeps its size, under directDomUpdates (#1266). A compensation write whose target exceeds the scroll maximum at write time is now recorded as clamped and re-issued once the sizer has grown — right after notify for consumers that size the container synchronously in onChange, and from _willUpdate for consumers that size it during a render. The clamped read-back keeps the retry pending; any other scroll event cancels it, so a user reading history is never yanked.

    Patch Changes

    • Recover the bottom pin when the browser clamps an end-anchored scroll compensation write. resizeItem compensates a size change by writing scrollTop before the consumer has committed the new total size, so when the grown item does not itself extend the scroll range the browser clamps the write to the old maximum and the viewport is left short of the end with no scroll event to correct it. Two cases hit this: paddingEnd > 0 with a growing last item, where the overflowing item only extends scrollHeight to its own end and the clamp lands exactly paddingEnd short (#1258); and a row above the last one growing while the last row keeps its size, under directDomUpdates (#1266). A compensation write whose target exceeds the scroll maximum at write time is now recorded as clamped and re-issued once the sizer has grown — right after notify for consumers that size the container synchronously in onChange, and from _willUpdate for consumers that size it during a render. The clamped read-back keeps the retry pending; any other scroll event cancels it, so a user reading history is never yanked.