Window-based virtual lists
A page renders a long list whose scroll container is the browser window.
TanStack · Function
windowScroll
windowScroll is TanStack Virtual’s built-in implementation for scrolling a virtualizer through the browser window. Framework adapters such as useWindowVirtualizer configure it automatically.
How it works
The documentation identifies windowScroll as a built-in scrolling implementation for a virtualizer. Framework adapters such as useWindowVirtualizer configure it automatically, so applications normally select the window adapter instead of invoking this helper directly.
Syntax
windowScroll(offset, options, instance)Parameters
| Name | Type | Description |
|---|---|---|
offset | number | Pixel offset to scroll toward. |
options | object | Information about measurement adjustments and requested scrolling behavior. |
instance | Virtualizer | The virtualizer instance performing the scroll. |
Returns
A scrolling function used by a virtualizer to scroll the window toward a pixel offset.
Key points
- TanStack Virtual exports windowScroll as one of its standard scrolling implementations.
- React adapters can configure the scrolling implementation for you, so direct use of windowScroll is often unnecessary.
- Scrolling is requested using a pixel offset rather than an item index.
- The invocation communicates whether smooth scrolling was requested.
Common mistakes
- Use the window-specific adapter when the browser window is the scroll container; useWindowVirtualizer configures the built-in implementation automatically.
- A scroll-element accessor can temporarily produce null, so code should tolerate the scroll target not being available during initial rendering.
Example: Window-scrolling virtual list
import { useWindowVirtualizer } from '@tanstack/react-virtual'
export function List({ items }: { items: string[] }) {
const virtualizer = useWindowVirtualizer({
count: items.length,
estimateSize: () => 36,
overscan: 5,
})
return (
<div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
{virtualizer.getVirtualItems().map((item) => (
<div
key={item.key}
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
transform: `translateY(${item.start}px)`,
}}
>
{items[item.index]}
</div>
))}
</div>
)
}This example uses the window adapter, which configures the virtualizer to scroll with the browser window rather than a dedicated element.
When to use it
Document-scrolling tables
A virtualized table occupies the page without its own overflow element.
Adapter-configured scrolling
An adapter must provide standard window scrolling without custom movement logic.
Interview questions
QWhat is windowScroll?
windowScroll is a built-in scroll implementation for TanStack Virtual. It supplies window-based scrolling behavior to a virtualizer, while framework adapters can configure it automatically.
Follow-up: How is it normally selected in a React application? Use useWindowVirtualizer for a window-scrolling list; useVirtualizer is intended for a specific scroll element.
QHow does windowScroll differ from elementScroll?
The built-in implementations are elementScroll and windowScroll. The former targets an element scroll container, while the latter targets the browser window.
Follow-up: What determines the correct choice? Identify which object owns the scrolling: the window or a dedicated element.
QWhat arguments does a custom scroll implementation receive?
The virtualizer's scroll implementation receives the target offset, adjustment information, smooth-scrolling behavior, and the virtualizer instance. That lets it perform scrolling while accounting for measurement corrections and requested behavior.
Follow-up: Why pass adjustments? Estimated and actual item sizes can differ, so the implementation may need to compensate for that difference.
Related
elementScrolluseVirtualizeruseWindowVirtualizerscrollToFngetScrollElement