NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm, #3588 most downloaded on npm
Headless UI for virtualizing scrollable elements in TS/JS + Frameworks
Latest stable
3.19.11
Last release 19 days ago
03 Nov 2026
Ships fairly regularly
a new release about every 2 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
4 years old
144 releases · first in 2022
Drag across the ruler to compare, or tap a release to open it.
### Patch Changes - #1363 `acaef5e` - fix(virtual-core): compute getOffsetForIndex (and the first write of scrollToIndex) from the current measurement
#1363 acaef5e - fix(virtual-core): compute getOffsetForIndex (and the first write of scrollToIndex) from the current measurements, not from those of the last render
#1291 bd08fe5 - Fix programmatic scrolling in horizontal RTL elements by converting logical offsets, including measurement adjustments, to negative DOM scroll offsets.
### Patch Changes - #1351 `9d7ff67` - Keep a full viewport of rows in the range when the scroll offset is past the end of the list, as it is after the
Your coding agent can read these notes before it upgrades. Set up the MCP server →
### Patch Changes - #1347 `35ad56d` - fix(virtual-core): stop a touch fling for a command issued during it on Android too - #1348 `979c1b4` - Avoid Re
#1347 35ad56d - fix(virtual-core): stop a touch fling for a command issued during it on Android too
#1348 979c1b4 - Avoid ResizeObserver loop errors when a synchronous resize render mounts or unmounts rows. Measure new rows immediately, defer their observation until the next frame, and stop observing detached rows before delivery ends.
### Patch Changes - #1340 `2343004` - fix(virtual-core): account for scrollMargin when deciding the viewport is at the end
### Patch Changes - #1335 `887e971` - fix(virtual-core): cancel stale anchor work on explicit scroll - #1337 `5d51f1d` - fix(virtual-core): hold a cla
### Patch Changes - #1326 `05bb4d3` - Measure the scroll viewport using client dimensions so borders and scrollbars do not obscure end-aligned items.
scrollAdjustments is deprecated: a correction is folded into scrollOffset at once, so it is always 0. Read scrollOffset alone; the getter stays.
#1330 56b2a63 - 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.
#1329 d2c7911 - 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.
#1324 9c762fe - fix(virtual-core): scroll commands and corrections that stalled or were lost (#1307)
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.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.#1332 6789f7a - 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.
#1325 77cb05e - 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.
#1318 4a1a4fd - 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
#1319 3c61b6e - fix(virtual-core): hold a scroll correction the element cannot take instead of writing it (#1287)
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.
#1324 9c762fe - refactor(virtual-core): simplify the scroll-correction state (no behaviour change)
moved flag.scrollAdjustments is deprecated: a correction is folded into scrollOffset at once, so it is always 0. Read scrollOffset alone; the getter stays.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.### Patch Changes - #1320 `269e8ed` - fix(virtual-core): with useAnimationFrameWithResizeObserver, request frames from the scroll element's window ins
### Patch Changes - #1316 `f211d3a` - refactor(virtual-core): simplify the scroll-correction state: a scroll write is tracked until its read-back as o
f211d3a - 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).### Patch Changes - #1314 `3800fb3` - fix(virtual-core): treat iOS touchcancel like touchend so interrupted gestures cannot leave touch state stuck an
#1314 3800fb3 - fix(virtual-core): treat iOS touchcancel like touchend so interrupted gestures cannot leave touch state stuck and keep scroll anchoring suppressed
#1311 cb510cb - refactor(virtual-core): track an in-flight scroll command's lifecycle as one phase instead of several flags (no behaviour change)
### Patch Changes - #1310 `7aa34f6` - fix(virtual-core): let a user scroll end a non-smooth scrollToIndex before reconcile has seen it land, so a late
#1310 7aa34f6 - 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
#1309 e7a0a92 - 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
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 befor
92c697f - fix(virtual-core): keep lanes aligned after changing lanes with measureElement (#1036)
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.### Minor Changes - #1300 `43675bc` - feat(virtual-core): add cancelScroll() to stop an in-flight scrollToIndex / scrollToOffset / scrollBy / scrollTo
43675bc - 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 (#1285)#1276 9df47a3 - 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().
#1293 c644f10 - fix(virtual-core): don't cache a 0 size when measureElement receives a node that isn't attached to the document yet
#1294 2a631f4 - 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.
### Patch Changes - #1284 `06d1b6b` - Read the current scroll offset when the debounced scroll-end fallback fires so measurement adjustments made sinc
#1284 06d1b6b - 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.
#1248 2c0a0ea - 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.
Preserve item keys in the lazy measurement cache so a stable getItemKey callback reading mutable data cannot change the identity of previously measure
#1272 ab3278c - 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 - #1260 `4a0adf3` - Recover the bottom pin when the browser clamps an end-anchored scroll compensation write. resizeItem compensates
4a0adf3 - 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 - #1256 `a0a411e` - Cancel the pending isScrolling reset when a scroll observer is torn down, and reset isScrolling and scrollDirect
#1256 a0a411e - Cancel the pending isScrolling reset when a scroll observer is torn down, and reset isScrolling and scrollDirection in cleanup() so they don't stay stuck after the scroll element changes or is removed.
#1246 d2cf98b - Ignore connected measurement nodes whose indexes are outside the current item count.
### Patch Changes - #1239 `a5417b4` - Fix a one-frame viewport jump when above-viewport rows resize while scrolling up (#1227). resizeItem writes scro
a5417b4 - Fix a one-frame viewport jump when above-viewport rows resize while scrolling up (#1227). resizeItem writes scrollTop synchronously inside the ResizeObserver callback to compensate for the size change, but then notified asynchronously — so the browser could paint a frame with the new scrollTop and the old item transforms, making the content jerk by the resize delta and snap back. When a compensation actually moves the scroll position, resizeItem now notifies synchronously so the transform commit lands in the same paint as the scroll write. Resizes that don't move the scroll position (below-fold measurements, iOS-deferred adjustments) keep the cheaper async notify.### Patch Changes - #1236 `7ae32b5` - Stop the default scroll-adjustment heuristic from drifting the viewport when a viewport-spanning item grows. Pre
7ae32b5 - Stop the default scroll-adjustment heuristic from drifting the viewport when a viewport-spanning item grows. Previously any item whose top sat above the fold (itemStart < scrollOffset) had its size delta compensated on every re-measure — including a streaming chat message that spans the fold and grows at its bottom, dragging scrollTop downward token by token (#1218). Re-measurements now only compensate items that are entirely above the fold (itemStart + itemSize <= scrollOffset); growth below the anchor point leaves the scroll position untouched. First measurements (estimate→actual) still compensate any above-fold item, and a custom shouldAdjustScrollPositionOnItemSizeChange still overrides the default.Absolute scroll commands (scrollToOffset / scrollToIndex / scrollToEnd) derive their target from current measurements, so a pending deferred delta is
#1230 1e3b908 - Clamp the tracked scrollOffset at 0 when applying end-anchor measurement compensation and when re-anchoring in setOptions. Previously, with anchorTo: 'end' and content shorter than the viewport, items measuring smaller than their estimates drove the tracked offset negative with no scroll event to ever correct it — getDistanceFromEnd() reported a permanent phantom distance and iOS deferred measurement corrections stayed wedged forever.
#1235 7dcfc07 - Stop iOS-deferred scroll adjustments from replaying stale deltas after the position is already correct (#1233). On iOS WebKit the end-anchored virtualizer defers scroll compensation while the scroller is live and replays it once settled, but two cases replayed a delta whose premise no longer held:
scrollToOffset / scrollToIndex / scrollToEnd) derive their target from current measurements, so a pending deferred delta is already stale — it now invalidates the deferral instead of letting it replay and shift the list off the just-established position. Relative commands (scrollBy) keep the deferral.anchorTo: 'end', a row above the viewport re-measuring smaller lets the browser clamp scrollTop onto the new bottom (already the correct position); the flush now drops the stale negative compensation instead of replaying it and lifting the view off the bottom. Positive deltas still replay, since content growth above does not clamp.### Patch Changes - #1224 `6cbecd8` - Improve multi-lane virtualization performance: replace the backward scan in getMeasurements with an incremental
#1224 6cbecd8 - Improve multi-lane virtualization performance: replace the backward scan in getMeasurements with an incremental per-lane argmin (O(lanes) shortest-lane lookup). Placement output is unchanged and the single-lane fast path is untouched.
#1223 d49cc52 - Made gap option changes invalidate measurements
#1220 cf7834d - Reset iOS gesture/deferral state in cleanup() so it no longer leaks across scroll element swaps.
applyScrollAdjustment folds the pending adjustment into scrollOffset eagerly, so the browser's scroll event for that write arrives at exactly the held
#1206 767ead4 - Cut per-scroll-frame allocations on the default lanes === 1 path. Range computation previously allocated an options object and two closures on every scroll event; it now does the same work allocation-free, reducing GC pressure during continuous scroll.
#1212 bc8643b - Don't latch a scroll direction from the read-back of the virtualizer's own adjustment write
applyScrollAdjustment folds the pending adjustment into scrollOffset eagerly, so the browser's scroll event for that write arrives at exactly the held offset. The scroll-direction computation treated that equality as 'backward', which made the default shouldAdjustScrollPositionOnItemSizeChange skip above-viewport re-measure compensation for the rest of the isScrollingResetDelay window — so during multi-frame reflows (e.g. a side pane's width animation re-wrapping rows while scrolled up) most frames went uncompensated and the viewport drifted. An event at the held offset carries no direction information, so the direction now stays unchanged in that case; real gestures always move the offset and still latch normally.
With anchorTo: 'end' and a dynamically growing last item (token streaming), resizeItem writes the scroll adjustment to scrollTop before the consumer h
#1208 b04f9ee - Skip redundant scroll events at unchanged offset
#1209 37be284 - Sync scrollOffset in applyScrollAdjustment so end-anchored streaming resize isn't lost to browser clamp
With anchorTo: 'end' and a dynamically growing last item (token streaming), resizeItem writes the scroll adjustment to scrollTop before the consumer has grown the sizer, so the browser clamps the write and no scroll event fires. scrollOffset stayed stale, the next tick's wasAtEnd check failed, and the viewport drifted away from the end. This fix carries the intended target in scrollOffset (zeroing scrollAdjustments) the same way the prepend path in setOptions does, so the next getVirtualDistanceFromEnd() reads the post-adjustment position.
### Patch Changes - #1199 `ef69ea3` - Fix "items jump while scrolling up": the default scroll-adjustment predicate now compensates scrollTop on the fi
ef69ea3 - Fix "items jump while scrolling up": the default scroll-adjustment predicate now compensates scrollTop on the first measurement of an above-viewport item even while scrolling backward (the estimate→actual delta must be absorbed), and only skips compensation for re-measurements during backward scroll to avoid the cascading jank### Minor Changes - #1186 `fbf3bdb` - Add useCachedMeasurements option to skip DOM measurement when the list is hidden (e.g. display: none). When enab
fbf3bdb - Add useCachedMeasurements option to skip DOM measurement when the list is hidden (e.g. display: none). When enabled, the default measureElement returns the cached size or estimateSize fallback instead of reading the DOM, preventing ResizeObserver from resetting measurements to zero.Eagerly adjust scrollOffset on prepend to prevent one-frame jump with anchorTo: 'end'
Eagerly adjust scrollOffset on prepend to prevent one-frame jump with anchorTo: 'end' (#1176)
When items are prepended with anchorTo: 'end' and dynamic sizes, the virtualizer would compute the wrong visible range for one frame (using stale estimate-based positions) and then correct in the next frame via _willUpdate, producing a visible jump. This fix eagerly adjusts scrollOffset in setOptions during the render pass so calculateRange/getVirtualItems return the correct items immediately.
Add end-anchored virtualization support for chat, logs, and reverse feeds.
Add end-anchored virtualization support for chat, logs, and reverse feeds. (#1173)
New anchorTo: 'end' mode keeps the current visible item stable when older items are prepended, while preserving the existing start-anchored behavior by default. It also keeps an end-pinned viewport pinned when the last item grows during streaming output.
Add followOnAppend so new items scroll into view only when the viewport was already at the end, plus scrollEndThreshold, scrollToEnd(), getDistanceFromEnd(), and isAtEnd() helpers for chat-style integrations.
43675bc - 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 (#1285)### Minor Changes - #1219 `1323692` - Post-release follow-ups for the Marko adapter: full option parity for both tags (scrollMargin, enabled, isRtl, i
1323692 - Post-release follow-ups for the Marko adapter: full option parity for both tags
(scrollMargin, enabled, isRtl, isScrollingResetDelay, useScrollendEvent,
useAnimationFrameWithResizeObserver, laneAssignmentMode, useCachedMeasurements,
debug, custom measureElement; window tag adds horizontal and initialOffset),
named handle types (VirtualizerHandle / WindowVirtualizerHandle) whose .d.marko
declarations are generated into dist/tags at build time (via marko-type-check)
and type-checked in CI, a new Chat + Pretext example (calculated row heights via
@chenglou/pretext; streamed replies grow through resizeItem), browser e2e suites
for every example plus option-gate behavioral proofs, TypeScript-strict cleanups
across examples, and chat example improvements (accurate size estimate,
load-ahead history trigger, overflow-anchor handling).b4a76ca - Stop publishing the tags build's incremental state: marko-type-check writes
dist/tsconfig.tags.tsbuildinfo, which the files field shipped to npm and nx
cached as part of dist. Because @marko/type-check always runs incrementally, a
dist that carried that file but not dist/tags (which marko.json points at)
made every subsequent build a silent no-op — exit 0, nothing emitted — and any
consumer then failed to compile with
ENOENT: no such file or directory, scandir '.../dist/tags'. The build now removes
the file after emitting, so a build always produces dist/tags.iOS Safari momentum-scroll handling. Writing scrollTop while a finger (#1168)
is on the screen, during momentum decay, or while the page is in the
elastic-overscroll bounce zone all cancel the in-flight scroll in iOS
WebKit. The virtualizer previously had no iOS-specific handling, which
manifested as the recurring "scroll abruptly stops when content above
resizes" complaints on Safari mobile.
Adds three layers of protection, default-on, all transparent to consumers:
_iosDeferredAdjustment field instead of writing scrollTop.scrollTop within 1.5 px of a value we just wrote, the virtualizer
prefers the intended value rather than treating the round-trip as a
user scroll.scrollTop is outside [0, scrollHeight - clientHeight],
preventing a snap-back jolt at end-of-bounce. The next in-bounds
scroll event retries.Non-iOS code paths are unchanged. iOS detection is SSR-safe and cached after first call. Bundle cost is ~370 B gzip in the consumer-minified production build — kept default-on because iOS Safari is a large share of mobile traffic for the apps that use virtualization heavily.
Skip the scroll-position adjustment while the user is scrolling backward (#1168)
by default. When an above-viewport item resizes during backward scroll
(images load, content reflows, etc.) the prior behavior wrote scrollTop
to keep the visible window stable — but on backward scroll that write
fights the user's direction and produces visible "items jump up while I
scroll up" jank. This was the largest single complaint cluster in the
issue tracker (multiple recurring threads spanning years; users had
independently rediscovered the same workaround at least five times).
Forward-scroll and idle (mount-time) adjustments still fire as before
to preserve visual stability of the visible window. Consumers who want
the old behavior — adjusting on every above-viewport resize regardless
of direction — can supply shouldAdjustScrollPositionOnItemSizeChange
which is checked before the default branch.
Add takeSnapshot() instance method for scroll-restoration round-trips. (#1168)
Returns the currently-measured items as plain VirtualItem objects;
pair with the current scrollOffset to persist scroll position across
remounts (route navigation, list-view modals, etc.). The result feeds
back through the existing initialMeasurementsCache option:
const snapshot = virtualizer.takeSnapshot()
const offset = virtualizer.scrollOffset
// later, on remount:
useVirtualizer({
// …
initialMeasurementsCache: snapshot,
initialOffset: offset,
})
Closes the gap to virtua's takeCacheSnapshot() and react-virtuoso's
getState. Only items actually rendered (and thus measured) are
included; unmeasured items fall back to estimateSize on restore.
Mount-time, measurement, and memory rewrite for huge lists. The hot path (#1168)
through getMeasurements() no longer allocates a VirtualItem object per
index for single-lane lists; instead it fills a Float64Array of
start/size pairs and materializes VirtualItem objects lazily through a
Proxy-backed view when consumers index into them. Internal hot paths
(calculateRange, getVirtualItemForOffset, getTotalSize, resizeItem)
read directly from the typed-array storage to avoid the Proxy.
Also collapses a chain of smaller hotspots discovered in an audit pass:
the per-resize Map clone in resizeItem, the Object.entries+delete
deopt in setOptions, the Math.min(...pendingMeasuredCacheIndexes)
spread, the defaultRangeExtractor push growth pattern, the eager
measurementsCache reference invalidation, and the leaked elementsCache
entries when a ResizeObserver fires for a node React already replaced.
Headline impact (measured against actual Virtualizer instances with
vitest bench):
resizeItem storm of 10,000 measurements + final getMeasurements:
~1.9 s → ~1.3 ms (≈1382×) — this was the dominant Map-clone bugsetOptions × 10,000 calls (React-render-storm proxy): ~14 ms → ~1.3 ms
(11×)The lanes>1 path keeps the previous eager allocation (lane assignment is order-dependent and harder to defer cleanly); behavior is unchanged there.
No public API change. measurementsCache is still an
Array<VirtualItem>-shaped value supporting [i], .length, iteration,
etc. Internal consumers that previously read fields off VirtualItem
objects continue to do so transparently.
scrollToIndex(N, { behavior: 'smooth' }) on a dynamic-height list no (#1168)
longer snaps to behavior: 'auto' the moment a measurement shifts the
computed target offset. While the scroll is still more than a viewport
away from the new target, smooth scroll continues with the updated
endpoint; only on the final approach do we fall back to 'auto' for
precise landing. The user-visible effect is one continuous smooth
motion that subtly adjusts its endpoint as measurements arrive,
instead of the prior animation-then-snap pattern.
Also: once reconcileScroll reaches its stable-frames threshold, it
writes the exact target offset one final time. This is a no-op when
scrollTop already equals the target (the common case) but corrects
the rare subpixel-rounding case where smooth scroll undershoots by
less than 1 px.
Don't call getItemKey with a possibly-stale index when cleaning up (#1168)
elementsCache for a disconnected node. The cleanup now finds the
matching entry by node identity, so removing items from the end of
the list while a ResizeObserver still has the now-detached node
queued no longer throws (regression of #1148).
Two correctness fixes in the new code: (#1168)
measure() now resets pendingMin so a prior resizeItem() that left
it non-null can't preserve stale measurementsCache entries before that
index. The next rebuild is guaranteed to start at 0.scrollAdjustments. Without this, a resize landing between the flush
and the resulting scroll event would compute the next correction from
the stale pre-flush offset.#1334 91c2931 - Add setOptions to VirtualizerController and WindowVirtualizerController so virtualizer options can be updated after construction.
Previously the controller only accepted options once, in its constructor, so options derived from reactive Lit properties (count, estimateSize, horizontal, …) could never be re-applied. getVirtualizer().setOptions(...) is not a substitute: it replaces options wholesale and drops the controller's onChange wrapper, which is what asks the host to re-render.
setOptions takes a partial set of options, merges them over the options the controller already holds (skipping undefined, so an omitted value does not wipe a stored one), re-applies the host requestUpdate wrapper around onChange, and flushes the change:
willUpdate(changed: PropertyValues<this>) {
if (changed.has('count')) {
this.virtualizerController.setOptions({ count: this.count })
}
}
2343004]:
### Minor Changes - #1156 `2b39aef` - Add @tanstack/marko-virtual — a headless virtualisation adapter for Marko 6 using the runtime-tags API. Provides
directDomUpdates, directDomUpdatesMode, and containerRef. (#1180)bb4e0f1 - Re-export @tanstack/virtual-core from @tanstack/lit-virtual, so the core API (Virtualizer, defaultRangeExtractor, measureElement, the scroll observers and the shared types) can be imported from the adapter without adding @tanstack/virtual-core as a second dependency. Every other framework adapter already does this.4a0adf3]:
Updated dependencies \[`7ece2d5`]:
7ece2d5]:
Updated dependencies \[`54d771a`, `d3416c3`]:
be89e29]:
Updated dependencies \[`be89e29`]:
be89e29]:
ff83e94]:
fix(virtual-core): early return in \_measureElement for disconnected nodes
ff83e94]:
843109c]:
Updated dependencies \[`9067574`]:
9067574]:
843109c]:
scrollToIndex by adding a null guard for targetWindow inside the requestAnimationFrame callback (#1129)Updated dependencies \[`9067574`]:
9067574]:
21d9a46]:
Updated dependencies \[`21d9a46`]:
21d9a46]:
db6df21]:
Updated dependencies \[`db6df21`]:
db6df21]:
5a273bf]:
Updated dependencies \[`5a273bf`]:
5a273bf]:
feat(react-virtual): add useFlushSync option (#1100)
Adds a React-specific useFlushSync option to control whether flushSync is used for synchronous scroll correction during measurement.
The default behavior remains unchanged (useFlushSync: true) to preserve the best scrolling experience.
Disabling it avoids the React 19 warning about calling flushSync during render, at the cost of potentially increased visible whitespace during fast scrolling with dynamically sized items.
Updated dependencies [5a273bf]:
6d9274c]:
Updated dependencies \[`6d9274c`]:
6d9274c]:
Fix: Correct lane assignments when lane count changes dynamically (#1095)
Fixed a critical bug where changing the number of lanes dynamically would cause layout breakage with incorrect lane assignments. When the lane count changed (e.g., from 3 to 2 columns in a responsive masonry layout), some virtual items would retain their old lane numbers, causing out-of-bounds errors and broken layouts.
Root Cause: After clearing measurements cache on lane change, the virtualizer was incorrectly restoring data from initialMeasurementsCache, which contained stale lane assignments from the previous lane count.
Fix: Skip initialMeasurementsCache restoration during lane transitions by checking the lanesSettling flag. This ensures all measurements are recalculated with correct lane assignments for the new lane count.
Before:
// With lanes = 2
virtualItems.forEach((item) => {
columns[item.lane].push(item) // ❌ Error: item.lane could be 3
})
After:
// With lanes = 2
virtualItems.forEach((item) => {
columns[item.lane].push(item) // ✅ item.lane is always 0 or 1
})
This fix is essential for responsive masonry layouts where column count changes based on viewport width. No performance impact as it only affects the lane change transition path.
Fix: Notify framework when count changes to update getTotalSize() (#1085)
Fixed an issue where getTotalSize() would return stale values when the count option changed (e.g., during filtering or search operations). The virtualizer now automatically notifies the framework when measurement-affecting options change, ensuring the UI updates correctly without requiring manual useMemo workarounds.
Before: When filtering items, the list container would maintain its previous height, causing excessive blank space (when count decreased) or inaccessible items (when count increased).
After: Height updates automatically when count changes, providing the correct user experience.
This fix applies to all framework adapters and has minimal performance impact (< 0.1ms per change).
Updated dependencies [2542c5a, 96e32a6]:
Fix: Notify framework when count changes to update getTotalSize()
Fix: Notify framework when count changes to update getTotalSize() (#1085)
Fixed an issue where getTotalSize() would return stale values when the count option changed (e.g., during filtering or search operations). The virtualizer now automatically notifies the framework when measurement-affecting options change, ensuring the UI updates correctly without requiring manual useMemo workarounds.
Before: When filtering items, the list container would maintain its previous height, causing excessive blank space (when count decreased) or inaccessible items (when count increased).
After: Height updates automatically when count changes, providing the correct user experience.
This fix applies to all framework adapters and has minimal performance impact (< 0.1ms per change).
Updated dependencies [2542c5a, 96e32a6]:
Fix: Notify framework when count changes to update getTotalSize() (#1085)
Fixed an issue where getTotalSize() would return stale values when the count option changed (e.g., during filtering or search operations). The virtualizer now automatically notifies the framework when measurement-affecting options change, ensuring the UI updates correctly without requiring manual useMemo workarounds.
Before: When filtering items, the list container would maintain its previous height, causing excessive blank space (when count decreased) or inaccessible items (when count increased).
After: Height updates automatically when count changes, providing the correct user experience.
This fix applies to all framework adapters and has minimal performance impact (< 0.1ms per change).
fix: stabilize lane assignments in masonry layout (#1080)
Added lane assignment caching to prevent items from jumping between lanes when viewport is resized. Previously, items could shift to different lanes during resize due to recalculating "shortest lane" with slightly different heights.
Changes:
laneAssignments cache (Map<index, lane>) to persist lane assignmentslanes option changes or measure() is calledcount decreases (removes stale entries)fix(lit-virtual): create Virtualizer instance before hostConnected (#1061)
When creating an instance of the reactive controller in connectedCallback, calling addController will synchronously call hostConnected on the controller. This means that this.virtualizer will still be undefined.
Updated dependencies \[`d21ed98`]:
d21ed98]:
Updated dependencies \[`73fa867`]:
73fa867]:
Updated dependencies \[`b3b7e7d`]:
b3b7e7d]:
Updated dependencies \[`9e33cdb`]:
9e33cdb]:
Error: Unexpected undefined (#1004)Updated dependencies \[`60719f6`]:
60719f6]:
fix(virtual-core): prevent measurement jitter when scale is applied
e2d93c2]:
Updated dependencies \[`042616f`]:
042616f]:
042616f)Updated dependencies \[`51656d9`]:
51656d9]:
Updated dependencies \[`514b62d`, `f03d814`]:
Updated dependencies \[`02ef309`]:
02ef309]:
Version 3.13.2 - 2/25/25, 7:40 AM
Version 3.13.2 - 2/25/25, 7:40 AM
Version 3.13.1 - 2/25/25, 6:21 AM
Version 3.13.1 - 2/25/25, 6:21 AM
Version 3.13.0 - 2/7/25, 12:12 PM
Version 3.13.0 - 2/7/25, 12:12 PM
Version 3.12.1 - 2/7/25, 5:12 AM
Version 3.12.1 - 2/7/25, 5:12 AM
Version 3.12.0 - 2/3/25, 4:02 AM
Version 3.12.0 - 2/3/25, 4:02 AM
Version 3.11.3 - 1/27/25, 10:57 AM
Version 3.11.3 - 1/27/25, 10:57 AM
Version 3.11.2 - 12/16/24, 2:10 PM
Version 3.11.2 - 12/16/24, 2:10 PM
Version 3.10.9 - 11/7/24, 11:07 AM
Version 3.10.9 - 11/7/24, 11:07 AM
useScrollendEvent option (#875) (375cd83) by @hshojaVersion 3.10.8 - 9/16/24, 2:22 PM
Version 3.10.8 - 9/16/24, 2:22 PM
Version 3.10.7 - 9/4/24, 1:15 PM
Version 3.10.7 - 9/4/24, 1:15 PM
One column per quarter.