React Virtuoso is a high-performance virtual scroll component library designed for efficiently rendering large lists, grids, and tables in React applications. It achieves this by virtualizing items, meaning only the visible elements are rendered, significantly optimizing performance and memory usage, especially for thousands of items. The current stable version is 4.18.5, and the project maintains an active release cadence with frequent patch and minor updates. Key differentiators include automatic handling of variable and dynamic item sizes without requiring manual measurement, responsive container sizing that adapts seamlessly to parent and viewport changes (including complex flexbox layouts), and robust support for bi-directional endless scrolling through `startReached` and `endReached` callbacks. The library also offers specialized components like `GroupedVirtuoso` for lists with sticky headers, `VirtuosoGrid` for responsive grid layouts, and `TableVirtuoso` for virtualized tables, providing extensive customization options and integration capabilities with popular UI libraries like shadcn/ui, MUI, and Mantine.
npm install react-virtuosoVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates a basic `Virtuoso` component rendering a list of 5000 items with simulated variable heights within a fixed-height container, showcasing its core virtualization capabilities.
Upgrade `react-virtuoso` to version `4.18.5` or higher to ensure proper `useSyncExternalStore` detection and avoid tearing issues with React 18+ and 19+ concurrent rendering.
Ensure the `Virtuoso` component or its direct parent has a CSS `height` (e.g., `height: '100%'`, `height: '500px'`) or `max-height` to establish a scrollable viewport. Consider using a flexbox layout for responsive sizing.
Instead of `margin`, use `padding` on the item content or its internal elements to create spacing, or use CSS `gap` on the parent container if applicable. If margins are unavoidable, ensure they do not protrude outside the item container.
Use `React.memo` for the components rendered inside `itemContent` to prevent unnecessary re-renders. Implement simplified placeholders (skeletons) for heavy content while scrolling by hooking into the `isScrolling` callback. Optimize the rendering logic within `itemContent` to be as lightweight as possible.
Apply a `style={{ height: '...' }}` or `style={{ maxHeight: '...' }}` to the `Virtuoso` component or its parent element. For example, `style={{ height: '100%' }}`.Ensure that items rendered by `itemContent` are not empty and have a measurable size. Check for any CSS that might inadvertently collapse the item's dimensions. Enable debug logging (`logLevel={LogLevel.DEBUG}`) to inspect item sizes.Update your build tools (Webpack, Babel) to support ES Modules. Ensure your Webpack configuration includes a rule to process `.mjs` files if present, or upgrade to Webpack 5+.
Ensure that the `itemContent` prop is always passed a function that accepts `index` (and `groupIndex` for `GroupedVirtuoso`) and returns a React element. For example: `itemContent={(index) => <div>Item {index}</div>}`.