Render only rows near the viewport
Large vertical lists
TanStack · Hook
useVirtualizer
useVirtualizer creates a React Virtualizer for an HTML scroll element. It calculates the visible range for large collections while allowing the application to render and style the items.
How it works
The hook creates a Virtualizer configured for an HTML scroll element. It uses the item count and an estimated item size to calculate the scrollable range, exposes only the items near the viewport, and can refine positions through element measurement.
Syntax
function useVirtualizer<TScrollElement, TItemElement = unknown>(
options: PartialKeys<
ReactVirtualizerOptions<TScrollElement, TItemElement>,
'observeElementRect' | 'observeElementOffset' | 'scrollToFn'
>,
): Virtualizer<TScrollElement, TItemElement>Parameters
| Name | Type | Description |
|---|---|---|
options | PartialKeys<ReactVirtualizerOptions<TScrollElement, TItemElement>, 'observeElementRect' | 'observeElementOffset' | 'scrollToFn'> | Partial ReactVirtualizerOptions, including the item count, scroll-element getter, estimated item size, and optional adapter configuration. |
Returns
Virtualizer<TScrollElement, TItemElement>
Key points
- useVirtualizer is the React-specific wrapper around TanStack Virtual's core virtualization engine.
- The hook is generic over both the scroll element type and the rendered item element type.
- getScrollElement supplies the current HTML element that owns scrolling.
- In React, useFlushSync controls whether synchronous flushSync updates are enabled and defaults to true.
Common mistakes
- The scroll container must be supplied through getScrollElement; useWindowVirtualizer instead when the browser window is the scrolling surface.
Example: Virtualized React list
import * as React from 'react'
import { useVirtualizer } from '@tanstack/react-virtual'
export function VirtualList() {
const parentRef = React.useRef<HTMLDivElement>(null)
const virtualizer = useVirtualizer({
count: 10000,
getScrollElement: () => parentRef.current,
estimateSize: () => 35,
})
return (
<div ref={parentRef} style={{ height: 400, overflow: 'auto' }}>
<div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
{virtualizer.getVirtualItems().map(item => (
<div key={item.key} ref={virtualizer.measureElement}
data-index={item.index}
style={{ position: 'absolute', top: 0, transform: `translateY(${item.start}px)` }}>
Row {item.index}
</div>
))}
</div>
</div>
)
}Creates a scrollable React list whose rendered rows are limited to the visible virtual range.
When to use it
Start with estimates and refine positions through measurement
Variable-size content
Keep markup and styling under application control
Custom React interfaces
Choose the element-based hook or its window-based counterpart
Window or element scrolling
Interview questions
QWhat does useVirtualizer return?
useVirtualizer is the React adapter hook for a standard Virtualizer that uses an HTML element as its scroll element. Its options configure the item count, scroll-element lookup, sizing behavior, and other virtualization settings.
Follow-up: How would window scrolling differ? Use useWindowVirtualizer, which returns a Virtualizer configured with window as the scroll element.
QWhat are the main inputs to useVirtualizer?
The hook takes a PartialKeys ReactVirtualizerOptions object. The adapter supplies defaults for observeElementRect, observeElementOffset, and scrollToFn, while application code provides the remaining virtualization configuration.
Follow-up: Why is the adapter headless? It supplies virtualization logic rather than markup or styles, so the application owns DOM structure and presentation.
QHow does the hook support large lists?
A virtualizer computes which indexes belong near the current viewport instead of requiring every item to be rendered. The item count establishes the collection size, and estimateSize gives the initial size model used to calculate the scroll range.
Follow-up: How can variable-height items be handled? Attach the virtualizer's measurement mechanism to rendered elements so observed sizes refine the initial estimate.
Related
useWindowVirtualizerVirtualizerReactVirtualizerOptions@tanstack/react-virtual