A virtual scroll React component for efficiently rendering large scrollable lists, grids, tables, and feeds
npm install react-virtuoso   
React components for efficiently rendering large lists, grids, and tables with virtualization.
| Component | Purpose |
| ----------------- | -------------------------------------------- |
| Virtuoso | Flat lists |
| GroupedVirtuoso | Groups of items with sticky group headers |
| VirtuosoGrid | Same-sized items in a responsive grid layout |
| TableVirtuoso | Tables with virtualized rows |
- Variable item sizes - handles items with different heights automatically, no manual measurement needed
- Dynamic size changes - observes item size changes via ResizeObserver and readjusts automatically
- Responsive container sizing - adapts to parent/viewport size changes, safe for flexbox layouts
- Bi-directional endless scrolling - supports startReached and endReached callbacks for loading data on demand
- Press to load more - append or prepend items while retaining scroll position
- Initial scroll position - start from any location, skipping initial rendering of earlier items
- Customizable markup - custom Header, Footer, Scroller, and item wrapper components
- UI library integration - works with shadcn/ui, MUI, Mantine, and other component libraries
- Drag-and-drop support - integrates with drag-and-drop libraries through custom components
``bash`
npm install react-virtuoso
Add the Virtuoso Component to your React project. The bare minimum it needs is a height for its container (either explicitly set, or adjusted through a parent flexbox), the number of items to display, and a callback to render the item content.
`tsx live
import { Virtuoso } from 'react-virtuoso'
export default function App() {
return Item {index}} />
}
`
The GroupedVirtuoso component is similar to the "flat" Virtuoso, with the following differences:
- Instead of totalCount, the Component accepts groupedCounts: number[], which specifies the amount of items in each group.[20, 30]
For example, passing will render two groups with 20 and 30 items each;item
- In addition the render prop, the Component requires an additional group render prop,group
which renders the group header. The callback receives the zero-based group index as a parameter;itemContent
- The render prop gets called with an additional second parameter, groupIndex: number.
`tsx live
import { GroupedVirtuoso } from 'react-virtuoso'
const groupCounts = []
for (let index = 0; index < 1000; index++) {
groupCounts.push(10)
}
export default function App() {
return (
groupCounts={groupCounts}
groupContent={(index) => {
return (
// add background to the element to avoid seeing the items below it
Check the
grouped numbers,
grouped by first letter and
groups with load on demand
examples.
$3
The
component works like the Virtuoso one, but with HTML tables. It supports window scrolling, sticky headers, and fixed columns.`tsx live
import { TableVirtuoso } from 'react-virtuoso'export default function App() {
return (
data={Array.from({ length: 100 }, (_, index) => ({
name:
User ${index},
description: ${index} description,
}))}
itemContent={(index, user) => (
<>
{user.name}
{user.description}
)}
/>
)
}
`$3
The
component displays same sized items in multiple columns.
The layout and item sizing is controlled CSS class properties or styled containers,
which allows you to use media queries, min-width, percentage, etc.`tsx live
import { VirtuosoGrid, VirtuosoGridProps } from 'react-virtuoso'
import { forwardRef } from 'react'// Ensure that the component definitions are not declared inline in the component function,
// Otherwise the grid will remount with each render due to new component instances.
const gridComponents: VirtuosoGridProps['components'] = {
List: forwardRef(({ style, children, ...props }, ref) => (
{...props}
style={{
display: 'flex',
flexWrap: 'wrap',
...style,
}}
>
{children}
const ItemWrapper = ({ children, ...props }) => (
style={{
display: 'flex',
flex: 1,
textAlign: 'center',
padding: '1rem 1rem',
border: '1px solid gray',
whiteSpace: 'nowrap',
}}
>
{children}
export default function App() {
return (
<>
totalCount={1000}
components={gridComponents}
itemContent={(index) =>
/>
)
}
`
Several factors affect the component's performance.
The first and most important one is the _size of the visible area_.
Redrawing more items takes more time and reduces the frame rate.
To see if this affects you, reduce the component width or height;
Set the style property to something like {{width: '200px'}}.
Next, if the items are complex or slow to render, use React.memo for the itemContent contents.
`jsx
// Item contents are cached properly with React.memo
const InnerItem = React.memo(({ index }) => {
React.useEffect(() => {
console.log('inner mounting', index)
return () => {
console.log('inner unmounting', index)
}
}, [index])
return Item {index}
})
// The callback is executed often - don't inline complex components in here.
const itemContent = (index) => {
console.log('providing content', index)
return
}
const App = () => {
return
}
ReactDOM.render(
`
You can experiment with the increaseViewportBy property that specifies100px
how much more to render in addition to the viewport's visible height.
For example, if the component is tall, setting the increaseViewportBy
to will cause the list to render at least 250px of content.
Loading images and displaying complex components while scrolling can cause jank.
To fix that, you can hook to the isScrolling callback and replace
the problematic content in the item with a simplified one.
Check the scroll handling example for a possible implementation.
Setting CSS margins to the content or the item elements is the Kryptonite of Virtuoso's content measuring mechanism - the contentRect measurement does not include them.
If this affects you, the total scroll height will be miscalculated, and the user won't be able to scroll all the way down to the list.
To avoid that, if you are putting paragraphs and headings inside the item, make sure that the top/bottom elements' margins do not protrude outside of the item container.
` Item {index}jsx``
item={(index) => (
)}
/>
A few more common problems are present in the troubleshooting section.
- Documentation
- API Reference
- Examples
- Contributing
- Changelog
- License