Virtualizing Large Lists in React Applications
react-virtualized, react-window, and react-virtual are libraries designed to handle rendering large datasets efficiently in React. They use a technique called windowing or virtualization, which only renders the items currently visible in the viewport. This approach drastically reduces DOM node count and improves scrolling performance. While react-virtualized is the legacy option with many built-in components, react-window is its lighter, modern successor focused on core windowing. react-virtual (now part of TanStack) offers a headless, hook-based approach that works across multiple frameworks.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Virtualizing Large Lists in React Applications
When building data-heavy dashboards or feeds, rendering thousands of DOM nodes at once will slow down your application. react-virtualized, react-window, and react-virtual solve this by only rendering the items currently visible on the screen. While they share the same goal, their architectures and maintenance status differ significantly. Let's compare how they handle common engineering challenges.
ðïļ Architecture & API Style: Components vs Hooks
react-virtualized relies on heavy class-based components.
- You import specific components like
<List>or<Grid>. - Props are passed directly to configure behavior.
- Less flexible for custom DOM structures.
// react-virtualized: Component-based
import { List } from 'react-virtualized';
<List
width={600}
height={400}
rowCount={1000}
rowHeight={50}
rowRenderer={({ index, style }) => (
<div style={style}>Row {index}</div>
)}
/>
react-window uses function components with a render prop pattern.
- You wrap your items in
<FixedSizeList>or<VariableSizeList>. - The child function provides
indexandstyle. - Cleaner API but still component-bound.
// react-window: Component with render prop
import { FixedSizeList } from 'react-window';
<FixedSizeList
width={600}
height={400}
itemCount={1000}
itemSize={50}
>
{({ index, style }) => (
<div style={style}>Row {index}</div>
)}
</FixedSizeList>
react-virtual provides a headless hook.
- You call
useVirtualizerto get virtual items. - You map over the items and apply styles manually.
- Maximum flexibility for custom layouts.
// react-virtual: Hook-based
import { useVirtualizer } from '@tanstack/react-virtual';
const virtualizer = useVirtualizer({
count: 1000,
getScrollElement: () => parentRef.current,
estimateSize: () => 50,
});
return (
<div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
<div style={{ height: virtualizer.getTotalSize() }}>
{virtualizer.getVirtualItems().map((virtualItem) => (
<div key={virtualItem.key} style={{ transform: `translateY(${virtualItem.start}px)` }}>
Row {virtualItem.index}
</div>
))}
</div>
</div>
);
ð Handling Container Sizes: Built-in vs External
Resizing the virtual list when the window or container changes is a common requirement.
react-virtualized includes <AutoSizer> out of the box.
- Wraps the list and passes width/height props.
- Convenient but adds bundle weight even if unused elsewhere.
// react-virtualized: Built-in AutoSizer
import { List, AutoSizer } from 'react-virtualized';
<AutoSizer>
{({ height, width }) => (
<List
width={width}
height={height}
rowCount={1000}
rowHeight={50}
rowRenderer={({ index, style }) => (
<div style={style}>Row {index}</div>
)}
/>
)}
</AutoSizer>
react-window requires a separate package.
- You must install
react-virtualized-auto-sizer. - Keeps the core library lightweight.
- API is nearly identical to the legacy version.
// react-window: External AutoSizer
import { FixedSizeList } from 'react-window';
import AutoSizer from 'react-virtualized-auto-sizer';
<AutoSizer>
{({ height, width }) => (
<FixedSizeList
width={width}
height={height}
itemCount={1000}
itemSize={50}
>
{({ index, style }) => (
<div style={style}>Row {index}</div>
)}
</FixedSizeList>
)}
</AutoSizer>
react-virtual handles resizing via observers.
- The hook uses ResizeObserver internally.
- No extra wrapper component needed.
- You just need a ref on the scrollable parent.
// react-virtual: Observer-based
import { useVirtualizer } from '@tanstack/react-virtual';
const parentRef = useRef(null);
const virtualizer = useVirtualizer({
count: 1000,
getScrollElement: () => parentRef.current,
estimateSize: () => 50,
// ResizeObserver is handled internally
});
return (
<div ref={parentRef} style={{ overflow: 'auto' }}>
{/* Virtual items rendered here */}
</div>
);
ð ïļ Maintenance & Future Proofing
Long-term support is critical when choosing infrastructure libraries.
react-virtualized is in maintenance mode.
- The original author recommends
react-windowfor new work. - Bugs are fixed, but no new features are added.
- Larger bundle size due to legacy code.
// react-virtualized: Legacy status
// â ïļ Not recommended for new projects
import { List } from 'react-virtualized';
react-window is actively maintained.
- Designed as the modern replacement for
react-virtualized. - Stable API with focused scope.
- Best choice for standard React lists and grids.
// react-window: Active standard
// â
Recommended for React-specific projects
import { FixedSizeList } from 'react-window';
react-virtual is part of the TanStack ecosystem.
- Actively developed alongside TanStack Table and Query.
- Framework-neutral (works with Solid, Vue, Svelte).
- Best choice for custom needs or multi-framework teams.
// react-virtual: Modern headless
// â
Recommended for custom layouts or non-React frameworks
import { useVirtualizer } from '@tanstack/react-virtual';
ðĪ Similarities: Shared Ground Between Libraries
Despite their differences, all three libraries solve the same core problem using similar underlying math.
1. ð DOM Reduction
- All three only render visible rows.
- Keeps the DOM light even with 10,000+ items.
// All libraries: Render only visible items
// Instead of 1000 divs, only ~10 are in the DOM
2. ð Absolute Positioning
- Items are positioned using
transformortop/left. - Ensures smooth scrolling without layout thrashing.
// All libraries: Use inline styles for position
style={{ transform: `translateY(${offset}px)` }}
3. ð Scroll Event Listening
- All attach listeners to the scroll container.
- Calculate visible range based on scroll offset.
// All libraries: Listen to scroll events
// Internal logic calculates startIndex and endIndex
ð Summary: Key Differences
| Feature | react-virtualized | react-window | react-virtual |
|---|---|---|---|
| API Style | ð§ą Class Components | âïļ Function Components | ðŠ Hooks (Headless) |
| Bundle Size | ð Heavy | ðŠķ Light | ðŠķ Light |
| AutoSizer | â Built-in | â Separate Package | â Internal Observer |
| Maintenance | â ïļ Legacy | â Active | â Active |
| Framework | âïļ React Only | âïļ React Only | ð Framework Neutral |
ðĄ The Big Picture
react-virtualized is the legacy option ð°ïļ â avoid it for new work unless you are stuck maintaining old code. It has too much weight for modern apps.
react-window is the standard choice ð for React projects â it is light, stable, and does exactly what most teams need without extra complexity.
react-virtual is the flexible choice ð ïļ for custom needs â use it if you need headless logic, custom layouts, or support for frameworks beyond React.
Final Thought: For most React developers, react-window offers the best balance of performance and ease of use. If you need more control or framework neutrality, react-virtual is the modern alternative.
How to Choose: react-window vs react-virtualized vs react-virtual
- react-window:
Choose
react-windowif you need a reliable, React-specific solution for lists or grids with minimal overhead. It is the recommended successor toreact-virtualizedby the same author and offers better performance for standard use cases. You will need to pair it withreact-virtualized-auto-sizerfor dynamic container sizing. - react-virtualized:
Choose
react-virtualizedonly if you are maintaining an existing codebase that already depends on it. It includes many built-in components like Grid and Table, but it is heavier and no longer receives active feature development. For new projects, this package is considered legacy and should be avoided in favor of lighter alternatives. - react-virtual:
Choose
react-virtualif you want a headless solution that gives you full control over rendering logic. It uses hooks instead of components, making it flexible for custom layouts or non-React frameworks like Solid or Vue. This option requires more setup but avoids locking you into specific component structures.
Popular Comparisons
README for react-window
react-window is a component library that helps render large lists of data quickly and without the performance problems that often go along with rendering a lot of data. It's used in a lot of places, from React DevTools to the Replay browser.
Support
If you like this project there are several ways to support it:
The following wonderful companies and individuals have sponsored react-window:
Installation
Begin by installing the library from NPM:
npm install react-window
TypeScript types
TypeScript definitions are included within the published dist folder
FAQs
Frequently asked questions can be found here.
Documentation
Documentation for this project is available at react-window.vercel.app.
List
Renders data with many rows.
Required props
| Name | Description |
|---|---|
| rowComponent | React component responsible for rendering a row. This component will receive an âđïļ The prop types for this component are exported as |
| rowCount | Number of items to be rendered in the list. |
| rowHeight | Row height; the following formats are supported:
âđïļ Percentage heights can't be resolved during server rendering unless a â ïļ Dynamic row heights are not as efficient as predetermined sizes. It's recommended to provide your own height values if they can be determined ahead of time. |
| rowProps | Additional props to be passed to the row-rendering component. List will automatically re-render rows when values in this object change. â ïļ This object must not contain |
Optional props
| Name | Description |
|---|---|
| className | CSS class name. |
| style | Optional CSS properties. The list of rows will fill the height defined by this style. |
| children | Additional content to be rendered within the list (above rows). This property can be used to render things like overlays or tooltips. |
| defaultHeight | Default height of list (in pixels) for initial render, before its actual height has been measured. âđïļ Lists can't be measured during server rendering, so this value determines how many rows are server rendered.
It's recommended to set this to the expected height of the list (or to specify a pixel height via the |
| defaultScrollOffset | Initial scroll offset (in pixels) of the list. This value is only applied once, when the list first mounts with at least one row. âđïļ Server-rendered HTML can't be pre-scrolled, so server rendering always starts at the first row; the default scroll offset is applied once the list hydrates. â ïļ If the list can't be scrolled that far when the offset is applied (e.g. it is hidden with |
| listRef | Ref used to interact with this component's imperative API. This API has imperative methods for scrolling and a getter for the outermost DOM element. âđïļ The |
| onResize | Callback notified when the List's outermost HTMLElement resizes. This may be used to (re)scroll a row into view. |
| onRowsRendered | Callback notified when the range of visible rows changes. |
| overscanCount | How many additional rows to render outside of the visible area. This can reduce visual flickering near the edges of a list when scrolling. |
| rowKey | Lists use the row index as a âđïļ Custom keys can ensure better UX for sortable or filterable lists, particularly if your row components are stateful. Refer to the React documentation for more info. â ïļ This prop cannot be auto-memoized because it is called during render.
It is important to always |
| scrollElement | Element that scrolls the list, for lists that scroll along with other content (e.g. the page):
The list renders at its full height and only renders the rows visible within the scroll element's viewport. Its position within the scroll element is measured whenever it renders, scrolls, or resizes, and whenever content before it is resized, inserted, or removed (e.g. an image loading above the list).
âđïļ While the scroll element is â ïļ The list itself doesn't scroll, so its |
| tagName | Can be used to override the root HTML element rendered by the List component. The default value is "div", meaning that List renders an HTMLDivElement as its root. â ïļ In most use cases the default ARIA roles are sufficient and this prop is not needed. |
Grid
Renders data with many rows and columns.
âđïļ Unlike List rows, Grid cell sizes must be known ahead of time.
Either static sizes or something that can be derived (from the data in CellProps) without rendering.
Required props
| Name | Description |
|---|---|
| cellComponent | React component responsible for rendering a cell. This component will receive âđïļ The prop types for this component are exported as |
| cellProps | Additional props to be passed to the cell-rendering component. Grid will automatically re-render cells when values in this object change. â ïļ This object must not contain |
| columnCount | Number of columns to be rendered in the grid. |
| columnWidth | Column width; the following formats are supported:
âđïļ Percentage widths can't be resolved during server rendering unless a |
| rowCount | Number of rows to be rendered in the grid. |
| rowHeight | Row height; the following formats are supported:
âđïļ Percentage heights can't be resolved during server rendering unless a |
Optional props
| Name | Description |
|---|---|
| className | CSS class name. |
| dir | Indicates the directionality of grid cells. âđïļ The directionality of an ancestor element can't be detected during server rendering; specify this prop explicitly for server-rendered right-to-left grids. âđïļ See HTML |
| style | Optional CSS properties. The grid of cells will fill the height and width defined by this style. |
| children | Additional content to be rendered within the grid (above cells). This property can be used to render things like overlays or tooltips. |
| columnKey | Grids use the column index as a âđïļ Custom keys can ensure better UX for sortable or filterable grids, particularly if your cell components are stateful. Refer to the React documentation for more info. â ïļ This prop cannot be auto-memoized because it is called during render.
It is important to always |
| defaultHeight | Default height of grid (in pixels) for initial render, before its actual height has been measured. âđïļ Grids can't be measured during server rendering, so this value determines how many rows are server rendered.
It's recommended to set this to the expected height of the grid (or to specify a pixel height via the |
| defaultScrollLeft | Initial horizontal scroll offset (in pixels) of the grid. This value is only applied once, when the grid first mounts with at least one column. âđïļ Server-rendered HTML can't be pre-scrolled, so server rendering always starts at the first column; the default scroll offset is applied once the grid hydrates. â ïļ If the grid can't be scrolled that far when the offset is applied (e.g. it is hidden with |
| defaultScrollTop | Initial vertical scroll offset (in pixels) of the grid. This value is only applied once, when the grid first mounts with at least one row. âđïļ Server-rendered HTML can't be pre-scrolled, so server rendering always starts at the first row; the default scroll offset is applied once the grid hydrates. â ïļ If the grid can't be scrolled that far when the offset is applied (e.g. it is hidden with |
| defaultWidth | Default width of grid (in pixels) for initial render, before its actual width has been measured. âđïļ Grids can't be measured during server rendering, so this value determines how many columns are server rendered.
It's recommended to set this to the expected width of the grid (or to specify a pixel width via the |
| gridRef | Imperative Grid API. âđïļ The |
| onCellsRendered | Callback notified when the range of rendered cells changes. |
| onResize | Callback notified when the Grid's outermost HTMLElement resizes. This may be used to (re)scroll a cell into view. |
| overscanCount | How many additional rows/columns to render outside of the visible area. This can reduce visual flickering near the edges of a grid when scrolling. |
| rowKey | Grids use the row index as a âđïļ Custom keys can ensure better UX for sortable or filterable grids, particularly if your cell components are stateful. Refer to the React documentation for more info. â ïļ This prop cannot be auto-memoized because it is called during render.
It is important to always |
| scrollElement | Element that scrolls the grid, for grids that scroll along with other content (e.g. the page):
The grid renders at its full height and only renders the rows (and columns) visible within the scroll element's viewport. Its position within the scroll element is measured whenever it renders, scrolls, or resizes, and whenever content before it is resized, inserted, or removed (e.g. an image loading above the grid).
âđïļ While the scroll element is â ïļ The grid's |
| tagName | Can be used to override the root HTML element rendered by the Grid component. The default value is "div", meaning that Grid renders an HTMLDivElement as its root. â ïļ In most use cases the default ARIA roles are sufficient and this prop is not needed. |