# What changed in vue-virtual-scroller

> 32 changes in vue-virtual-scroller 2 to 3 from its official release notes, upgrade guides and advisories: 1 breaking, 1 deprecations, 9 new APIs and options. Each one cited. Sources checked 2026-10-18. HTML: https://unstale.sh/npm/vue-virtual-scroller/

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

## vue-virtual-scroller 3

### Breaking changes

- handleScroll was removed from the return value as part of simplifying headless usage. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)

### Deprecations

- Deprecates the sizeDependencies prop. (3.0.1) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.1)

### New APIs and options

- Page mode supports an explicit scroll parent and can find the nearest parent scroller. (3.0.4) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.4)
- Adds the enabled option to all scroller composables and components. (3.0.3) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.3)
- DisableTransform was added. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)
- FlowMode was added. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)
- useTableColumnWidths was added. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)

### Performance

- Improves package tree shaking. (3.0.1) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.1)
- General performance improved, with no major garbage collection. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)

### Behavior and default changes

- itemSize has improved function support. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)
- KeyField can now be a function. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)
- The useDynamicScroller API was simplified. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)

### Fixes and other changes

- Sparse grid views are now counted when enforcing the item limit. (3.0.5) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.5)
- Identity changes in the dynamic scroller are handled better. (3.0.4) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.4)
- Preserves the last good range during transient sparse cache states to prevent viewport blanking. (3.0.4) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.4)
- Prevents blank rows during transient cache states. (3.0.4) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.4)
- Guards accumulator reads against a transient sparse size cache. (3.0.3) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.3)
- Reverts the size measurement freeze while scrolling. (3.0.2) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.2)
- Adds stability checks for view ids in dynamic and recycle scrollers. (3.0.1) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.1)
- A fix addresses duplicated views. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)
- The hidden view position was increased. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)
- The items watcher now fires when the upstream array mutates in place. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)
- Support was added for variable-size scroll window detection. (3.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v3.0.0)

## vue-virtual-scroller 2

### New APIs and options

- Grid scrolling can be virtualized across both axes. (2.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.0)
- Headless composables are available for using the library's functionality without its standard UI components. (2.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.0)
- Enhances useRecycleScroller with visiblePool. (2.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.0)
- Adds style stamping to useRecycleScroller. (2.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.0)

### Tooling

- Types are improved with generics. (2.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.0)

### Fixes and other changes

- Adds a guard for when el is undefined. (2.0.1) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.1)
- Requested frames and timeouts are cleared on unmount. (2.0.1) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.1)
- Improves shift, cache restore, and size handling for WindowScroller. (2.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.0)
- Fixes are made to WindowScroller. (2.0.0) — [release notes](https://github.com/Akryum/vue-virtual-scroller/releases/tag/v2.0.0)