npm / react-virtuoso

react-virtuoso

What changed in react-virtuoso 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-21.

1 breaking3 new APIs and options15 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.1 on npm

react-virtuoso 419 changes

Breaking changes 1

In GroupedVirtuoso and GroupedTableVirtuoso, the callback now receives the index of the last real item rather than an index including group headers, and no longer fires when every group is empty.
4.18.17release notes

New APIs and options 3

A custom List wrapper can render a ul instead of a div, with its forwarded ref typed to the chosen element; Item is unchanged.
4.18.14release notes
Adds a prop to ensure a minimum number of items are rendered before and after the viewport, useful when pixel-based overscan is insufficient for tall or collapsible items.
4.17.0release notes
Adds support for specifying a fixed size for groups in grouped virtuoso.
4.15.0release notes

Fixes and other changes 15

VirtuosoGrid clamps out-of-range scrollToIndex targets to the last available item.
4.18.19release notes
The initial size probe stays within existing items, avoiding calls to computeItemKey and itemContent with a non-existent index; empty groups probe only headers and reset size state when items arrive.
4.18.18release notes
TableVirtuoso now passes this optional prop to its resize observer instead of leaving it as a leftover prop on the scroller DOM.
4.18.16release notes
Clamps the initial item count to available data, renders no items for explicitly empty data, and recomputes list state when the value changes after mount.
4.18.15release notes
The compensating scroll now runs from a layout effect after the renderer acknowledges the DOM mutation, preventing a painted frame where the list is displaced by the prepended page.
4.18.13release notes
Window-scrolling lists are measured before entering the viewport so their estimated height is included in the document layout.
4.18.12release notes
Explicit undefined initial top-most item index values no longer crash when empty data updates to an object-form initial index.
4.18.10release notes
The initial top-most item index is clamped to the available range, preventing out-of-range values from starting the list at a blank or mid-list position.
4.18.9release notes
A default-positioned { index: 0 } is treated like 0, avoiding a redundant initial scroll and delayed followOutput.
4.18.9release notes
The location object passed to scrollToIndex is no longer mutated; defaults are applied to a shallow copy.
4.18.9release notes
Scroll target indexes beyond the available items are clamped to the last available item.
4.18.8release notes
Fixed horizontal Virtuoso item positioning and scrolling in RTL layouts.
4.18.7release notes
Fixes SSR layout collapse by rendering the window viewport in normal flow while preserving sticky top items.
4.18.6release notes
React 19+ now correctly uses useSyncExternalStore instead of falling back to the legacy useState+useLayoutEffect subscription path, avoiding potential tearing in concurrent rendering.
4.18.5release notes
Fixes atBottomStateChange in useWindowScroll lists when the Virtuoso instance is rendered below other page content.
4.18.4release notes