Getting Started with React Virtuoso
React Virtuoso is a family of React components that display large data sets using virtualized rendering, automatically handling variable item sizes and changes in items' sizes.
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 |
MessageList | Human/AI chat interfaces |
Virtuoso Message List
The VirtuosoMessageList
component is a newly released React component built specifically for human and AI chatbot conversations. Check out the live example.
License
The react-virtuoso
package is distributed under the MIT license. The VirtuosoMessageList
component and the contents of the @virtuoso.dev/message-list
package are distributed under a commercial license. See pricing for more details.
Feature Highlights
The Virtuoso components automatically handle items with variable heights. You don't have to hard-code or manually measure item sizes. The components observe changes of the items' sizes (for example, due to content load) and automatically readjust the scroll area size. The component container size itself is observed and list readjusts its display automatically when the browser or its parent container changes sizes. You can safely use the Virtuoso components in responsive flexbox layouts.
A common use case covered by the components' API is the bi-directional endless scrolling and the press to load more UI patterns. The components can be configured to start from an initial location, thus skipping the initial rendering (and the potential need of data loading) of earlier items. The components expose startReached
and endReached
callback properties, suitable for loading data on demand. After the data has been loaded, You can append or prepend additional items, while retaining the current scroll location.
The markup of the components is customizable by passing custom components as props, supporting optional Header and Footer, or even replacing the Scroller element with a custom one (usually when integrating third party scrollbar library). The custom components props allow the easy integration of your UI library of choice (e.g. shadcn/ui, MUI, Mantine), or even integrate drag-and-drop through a third-party library.
To get a better impression of what's possible, examine the various examples in the documentation, and skim through the API reference.
Installation (react-virtuoso)
The Virtuoso components are distributed as NPM packages.
To use the Virtuoso
, TableVirtuoso
, GroupedVirtuoso
, and VirtuosoGrid
components, install react-virtuoso
in your React project.
npm install react-virtuoso
Install the @virtuoso.dev/message-list
package to use the VirtuosoMessageList
component.
npm install @virtuoso.dev/message-list
Hello World
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.
loading...
VirtuosoMessageList
The Message List component is specifically built for human and/or AI chatbot conversations. Follow the instructions in the Virtuoso Message List guide to install and use the VirtuosoMessageList
component.
loading...
GroupedVirtuoso
The GroupedVirtuoso
component is similar to the "flat" Virtuoso
, with the following differences:
- Instead of
totalCount
, the Component acceptsgroupedCounts: number[]
, which specifies the amount of items in each group. For example, passing[20, 30]
will render two groups with 20 and 30 items each; - In addition the
item
render prop, the Component requires an additionalgroup
render prop, which renders the group header. Thegroup
callback receives the zero-based group index as a parameter; - The
itemContent
render prop gets called with an additional second parameter,groupIndex: number
.
loading...
Check the grouped numbers, grouped by first letter and groups with load on demand examples.
TableVirtuoso
The TableVirtuoso
component works like the Virtuoso
one, but with HTML tables. It supports window scrolling, sticky headers, and fixed columns.
loading...
VirtuosoGrid
The VirtuosoGrid
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.
loading...
Performance
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.
// 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 <div style={{ height: 30 }}>Item {index}</div>
})
// The callback is executed often - don't inline complex components in here.
const itemContent = (index) => {
console.log('providing content', index)
return <InnerItem index={index} />
}
const App = () => {
return <Virtuoso totalCount={100} itemContent={itemContent} style={{ height: '100%' }} />
}
ReactDOM.render(<App />, document.getElementById('root'))
You can experiment with the increaseViewportBy
property that specifies
how much more to render in addition to the viewport's visible height.
For example, if the component is 100px
tall, setting the increaseViewportBy
to 150
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.
Caveats
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.
<Virtuoso
totalCount={100}
item={index => (
<div>
<p style={{ margin: 0 }}>Item {index}</p>
</div>
)}
/>
A few more common problems are present in the troubleshooting section.