React Virtuoso is a simple, easy to use React virtualized list component that can render huge data sets. Out of the box, Virtuoso:

  • Handles items with variable dynamic height; no manual measurements or hard-coding of item heights necessary;
  • Supports grouping with sticky group headers (GroupedVirtuoso);
  • Supports responsive grid layout (VirtuosoGrid);
  • Automatically handles content resizing;
  • Can render footer at the end of the list;
  • Can pin the first N items to the top of the list.

Get Started

Install the package in your React project:

npm install react-virtuoso

Or, if yarn is your thing:

yarn add react-virtuoso

Add the component to your application:

import * as React from 'react'
import * as ReactDOM from 'react-dom'
import { Virtuoso } from 'react-virtuoso'

const App = () => (
  <Virtuoso
    style={{ width: '300px', height: '400px' }}
    totalCount={200}
    item={index => <div>Item {index}</div>}
  />
)

ReactDOM.render(<App />, document.getElementById('root'))

Grouping

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. 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 additional group render prop, which renders the group header. The group callback receives the zero-based group index as a parameter;
  • The item render prop gets called with an additional second parameter, groupIndex: number.

Check the grouped numbers, grouped by first letter and groups with load on demand examples.

Grid

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.

Check the responsive grid columns example for a sample implementation.

Footer

The component accepts an optional footer render property, which is rendered after all items. The footer can be used to host a "load more" button or an indicator that the user has reached the end of the list.

Check the footer, press load more and endless scrolling examples for practical applications of the footer.

Pinned Items

The component accepts an optional topItems property, that specifies how many of the items to keep "pinned" at the top of the list. Check the top items example.

Scroll to Index

The Virtuoso components provide an imperative scrollToIndex method with optional align that scrolls the specified item into view. GroupedVirtuoso exports convenience callback to obtain the group item indices in order to scroll to a given group.

Check the scroll to index and scroll to group examples for possible usage of the method.

Customize the Scroll Container

You can swap the virutoso scroller implementation in order to add custom scroll logic or to integrade a custom scrolling library (like React scrollbars).

Check the custom scroll container example for a starting point.

Performance Factors

Several factors affect the component performance. The first and most important one size of the visible area. Redrawing large 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 content in the item prop is complex / large, use React.memo for the item render prop contents.

You can experiment with the overscan property which specifies how much more to render in addition to the viewport visible height. For example, if the component is 100px tall, setting the overscan to 150 will cause the list to render at least 250px of content. In a nutshell, increasing the overscan causes less frequent re-renders, but makes each re-render more expensive (because more items will get replaced).

Loading images and displaying complex components while scrolling can cause jank. To fix that, you can hook to the scrollingStateChange callback and replace the complex content in the item with a simplified one. Check the scroll handling example for a possible implementation.

Finally, as a last resort, you can speed up things by hard-coding the size of the items using the itemHeight property. This will cause the component to stop measuring and observing the item sizes. Be careful with that option; ensure that the items won't change size on different resolutions.

Gotchas

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>
  )}
/>

Browser Support

When in grouped mode, Virtuoso uses position: sticky to keep the virtual viewport at top of the scroller. This does not work in IE 11.