rigel-mintaka · Oct 10, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 12, 2026
diff --git a/.changeset/shared-scroller-offscreen-range.md b/.changeset/shared-scroller-offscreen-range.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+Render only the last rows of a list that is above the viewport in a shared scroll element. The scroll offset is capped at the end of the scroll element, the list's end plus the content after it, rather than at the list's end, so a list that has the element to itself is capped as before.
diff --git a/benchmarks/CHANGELOG.md b/benchmarks/CHANGELOG.md
@@ -1,5 +1,89 @@
 # @tanstack/virtual-benchmarks
 
+## 0.0.29
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.26
+
+## 0.0.28
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.25
+
+## 0.0.27
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.24
+
+## 0.0.26
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.23
+
+## 0.0.25
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.22
+
+## 0.0.24
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.21
+
+## 0.0.23
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.20
+
+## 0.0.22
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.19
+
+## 0.0.21
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.18
+
+## 0.0.20
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.17
+
+## 0.0.19
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.16
+
+## 0.0.18
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/react-virtual@3.14.15
+
 ## 0.0.17
 
 ### Patch Changes

diff --git a/benchmarks/package.json b/benchmarks/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/virtual-benchmarks",
   "private": true,
-  "version": "0.0.17",
+  "version": "0.0.29",
   "type": "module",
   "scripts": {
     "dev": "vite",

diff --git a/docs/api/virtualizer.md b/docs/api/virtualizer.md
@@ -80,7 +80,7 @@ The sync parameter indicates whether scrolling is currently in progress. It is `
 overscan?: number
 ```
 
-The number of items to render above and below the visible area. Increasing this number will increase the amount of time it takes to render the virtualizer, but might decrease the likelihood of seeing slow-rendering blank items at the top and bottom of the virtualizer when scrolling. The default value is `1`.
+The number of items to render above and below the visible area. Increasing this number will increase the amount of time it takes to render the virtualizer, but might decrease the likelihood of seeing slow-rendering blank items at the top and bottom of the virtualizer when scrolling. The default value is `1`. When `lanes` is greater than `1`, overscan counts whole rows of `lanes` items, so every lane renders the same number of extra items.
 
 ### `horizontal`
 
@@ -146,7 +146,7 @@ This function is passed the index of each item and should return a unique key fo
 rangeExtractor?: (range: Range) => number[]
 ```
 
-This function receives visible range indexes and should return array of indexes to render. This is useful if you need to add or remove items from the virtualizer manually regardless of the visible range, eg. rendering sticky items, headers, footers, etc. The default range extractor implementation will return the visible range indexes and is exported as `defaultRangeExtractor`.
+This function receives visible range indexes and should return array of indexes to render. This is useful if you need to add or remove items from the virtualizer manually regardless of the visible range, eg. rendering sticky items, headers, footers, etc. The default range extractor implementation will return the visible range indexes and is exported as `defaultRangeExtractor`. When `lanes` is greater than `1`, `range.lanes` holds the lane count and `defaultRangeExtractor` applies `overscan` as whole rows; a custom extractor that computes its own indexes should do the same to keep lanes aligned.
 
 ### `scrollToFn`
 
@@ -177,6 +177,8 @@ observeElementRect: (
 
 An optional function that if provided is called when the scrollElement changes and should implement the initial measurement and continuous monitoring of the scrollElement's `Rect` (an object with `width` and `height`). It's called with the instance (which also gives you access to the scrollElement via `instance.scrollElement`. Built-in implementations are exported as `observeElementRect` and `observeWindowRect` which are automatically configured for you by your framework adapter's exported functions like `useVirtualizer` or `useWindowVirtualizer`.
 
+The built-in `observeElementRect` measures the visible client area (`clientWidth` and `clientHeight`), excluding borders and scrollbars. Custom implementations should report the same viewport dimensions.
+
 ### `observeElementOffset`
 
 ```tsx
@@ -592,14 +594,16 @@ virtualizer.shouldAdjustScrollPositionOnItemSizeChange = (
   delta,
   instance,
 ) => {
-  return item.start < instance.getScrollOffset() + instance.scrollAdjustments
+  return item.start < (instance.scrollOffset ?? 0)
 }
 ```
 
 The callback receives the resized `item`, the size `delta`, and the `instance`; return `true` to apply the scroll adjustment, `false` to skip it.
 
 On iOS WebKit, scroll-position writes are deferred regardless of this callback while a finger is on screen, during momentum-scroll, and during elastic-overscroll bounce. The cumulative delta is flushed in a single write once the scroll settles, preserving iOS's native momentum physics.
 
+On iOS 27 and later a write no longer stops a fling but is overridden by it within a frame, so a `scrollToIndex`, `scrollToOffset` or `scrollToEnd` issued during a fling is written once the fling ends (about 150ms after its last frame) rather than being lost; a drag before then cancels it, a tap does not.
+
 ### `isScrolling`
 
 ```tsx
@@ -623,3 +627,7 @@ scrollOffset: number
 ```
 
 This option represents the current scroll position along the scrolling axis. It is measured in pixels from the starting point of the scrollable area.
+
+It is a position in the list's layout, and it stays consistent with `getOffsetForIndex`, the argument to `scrollToOffset`, and `initialOffset`: restoring a saved value returns to the same layout position. That is the same item only while the items and sizes before it are unchanged; to restore across changes, pair it with `takeSnapshot()` and `initialMeasurementsCache` as described above, or scroll to the item with `scrollToIndex`.
+
+While a scroll correction is held, because a write to the element is impossible at that moment (a touch gesture or its momentum on iOS, or the element rubber-banding past an edge), `getVirtualItems()` and `getTotalSize()` describe what is rendered, shifted by the held amount so the rows on screen do not move, while `scrollOffset` keeps the layout position. The hold ends with a single write once the element can take it. Prefer `getVirtualItems()` positions over `item.start - scrollOffset` for where a row sits in the viewport, since that difference is off by the held amount for the length of the gesture or bounce.
diff --git a/docs/framework/lit/lit-virtual.md b/docs/framework/lit/lit-virtual.md
@@ -34,3 +34,28 @@ private windowVirtualizerController = new WindowVirtualizerController<TItemEleme
 ```
 
 This class stands of window-based `Virtualizer` instance configured to work with an HTML element as the scrollElement.
+
+## Updating options
+
+The controller reads options once, in its constructor. When a reactive property changes, pass the new values to `setOptions` from `willUpdate` (before render). `VirtualizerController` and `WindowVirtualizerController` both implement it.
+
+`setOptions` merges that partial over the options the controller already holds, including its defaults, and keeps the `onChange` wrapper that re-renders the host. Keys set to `undefined` are ignored, so a partial update does not erase an option from an earlier call.
+
+```ts
+@property({ type: Number })
+count = 1000
+
+private virtualizerController = new VirtualizerController(this, {
+  getScrollElement: () => this.scrollElementRef.value,
+  count: this.count,
+  estimateSize: () => 35,
+})
+
+protected willUpdate(changed: PropertyValues<this>) {
+  if (changed.has('count')) {
+    this.virtualizerController.setOptions({ count: this.count })
+  }
+}
+```
+
+Call `setOptions` on the controller. `getVirtualizer().setOptions(...)` replaces options wholesale, drops the host `onChange` wrapper, and leaves the controller's stored options stale.
diff --git a/examples/angular/chat/package.json b/examples/angular/chat/package.json
@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^20.2.0",
     "@angular/platform-browser-dynamic": "^20.2.0",
     "@angular/router": "^20.2.0",
-    "@tanstack/angular-virtual": "^6.1.0",
+    "@tanstack/angular-virtual": "^6.1.12",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.1"

diff --git a/examples/angular/dynamic/package.json b/examples/angular/dynamic/package.json
@@ -18,7 +18,7 @@
     "@angular/platform-browser-dynamic": "^20.2.0",
     "@angular/router": "^20.2.0",
     "@faker-js/faker": "^8.4.1",
-    "@tanstack/angular-virtual": "^6.1.0",
+    "@tanstack/angular-virtual": "^6.1.12",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.1"

diff --git a/examples/angular/fixed/package.json b/examples/angular/fixed/package.json
@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^20.2.0",
     "@angular/platform-browser-dynamic": "^20.2.0",
     "@angular/router": "^20.2.0",
-    "@tanstack/angular-virtual": "^6.1.0",
+    "@tanstack/angular-virtual": "^6.1.12",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.1"

diff --git a/examples/angular/infinite-scroll/package.json b/examples/angular/infinite-scroll/package.json
@@ -18,7 +18,7 @@
     "@angular/platform-browser-dynamic": "^20.2.0",
     "@angular/router": "^20.2.0",
     "@tanstack/angular-query-experimental": "5.80.7",
-    "@tanstack/angular-virtual": "^6.1.0",
+    "@tanstack/angular-virtual": "^6.1.12",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.1"

diff --git a/examples/angular/padding/package.json b/examples/angular/padding/package.json
@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^20.2.0",
     "@angular/platform-browser-dynamic": "^20.2.0",
     "@angular/router": "^20.2.0",
-    "@tanstack/angular-virtual": "^6.1.0",
+    "@tanstack/angular-virtual": "^6.1.12",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.1"

diff --git a/examples/angular/smooth-scroll/package.json b/examples/angular/smooth-scroll/package.json
@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^20.2.0",
     "@angular/platform-browser-dynamic": "^20.2.0",
     "@angular/router": "^20.2.0",
-    "@tanstack/angular-virtual": "^6.1.0",
+    "@tanstack/angular-virtual": "^6.1.12",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.1"

diff --git a/examples/angular/sticky/package.json b/examples/angular/sticky/package.json
@@ -18,7 +18,7 @@
     "@angular/platform-browser-dynamic": "^20.2.0",
     "@angular/router": "^20.2.0",
     "@faker-js/faker": "^8.4.1",
-    "@tanstack/angular-virtual": "^6.1.0",
+    "@tanstack/angular-virtual": "^6.1.12",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.1"

diff --git a/examples/angular/table/package.json b/examples/angular/table/package.json
@@ -19,7 +19,7 @@
     "@angular/router": "^20.2.0",
     "@faker-js/faker": "^8.4.1",
     "@tanstack/angular-table": "8.21.3",
-    "@tanstack/angular-virtual": "^6.1.0",
+    "@tanstack/angular-virtual": "^6.1.12",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.1"