# What changed in react-virtuoso

> 19 changes in react-virtuoso 4 from its official release notes, upgrade guides and advisories: 1 breaking, 3 new APIs and options. Each one cited. Sources checked 2026-10-21. HTML: https://unstale.sh/npm/react-virtuoso/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## react-virtuoso 4

### Breaking changes

- 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.17) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.17)

### New APIs and options

- 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.14) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.14)
- 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.0) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.17.0)
- Adds support for specifying a fixed size for groups in grouped virtuoso. (4.15.0) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.15.0)

### Fixes and other changes

- VirtuosoGrid clamps out-of-range scrollToIndex targets to the last available item. (4.18.19) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.19)
- 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.18) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.18)
- TableVirtuoso now passes this optional prop to its resize observer instead of leaving it as a leftover prop on the scroller DOM. (4.18.16) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.16)
- 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.15) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.15)
- 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.13) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.13)
- Window-scrolling lists are measured before entering the viewport so their estimated height is included in the document layout. (4.18.12) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.12)
- Explicit undefined initial top-most item index values no longer crash when empty data updates to an object-form initial index. (4.18.10) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.10)
- 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.9) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.9)
- A default-positioned `{ index: 0 }` is treated like `0`, avoiding a redundant initial scroll and delayed `followOutput`. (4.18.9) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.9)
- The location object passed to `scrollToIndex` is no longer mutated; defaults are applied to a shallow copy. (4.18.9) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.9)
- Scroll target indexes beyond the available items are clamped to the last available item. (4.18.8) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.8)
- Fixed horizontal Virtuoso item positioning and scrolling in RTL layouts. (4.18.7) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.7)
- Fixes SSR layout collapse by rendering the window viewport in normal flow while preserving sticky top items. (4.18.6) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.6)
- 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.5) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.5)
- Fixes atBottomStateChange in useWindowScroll lists when the Virtuoso instance is rendered below other page content. (4.18.4) — [release notes](https://github.com/petyosi/react-virtuoso/releases/tag/react-virtuoso%404.18.4)