react-virtuoso

What is react-virtuoso?

react-virtuoso is a performant and easy-to-use React component for rendering large lists and tabular data. It provides a virtualized list component that only renders the visible items, significantly improving performance for large datasets.

What are react-virtuoso's main functionalities?

Basic List

This code demonstrates how to create a basic virtualized list with 1000 items using react-virtuoso. Only the visible items are rendered, improving performance.

```jsx
import React from 'react';
import { Virtuoso } from 'react-virtuoso';

const App = () => (
  <Virtuoso
    totalCount={1000}
    itemContent={index => <div>Item {index}</div>}
  />
);

export default App;
```

Grouped List

This code demonstrates how to create a grouped list using react-virtuoso. The list is divided into groups, and each group and its items are rendered only when they are visible.

```jsx
import React from 'react';
import { Virtuoso } from 'react-virtuoso';

const App = () => (
  <Virtuoso
    groupCounts={[3, 2, 5]}
    groupContent={index => <div>Group {index}</div>}
    itemContent={(index, groupIndex) => <div>Item {index} in Group {groupIndex}</div>}
  />
);

export default App;
```

Table

This code demonstrates how to create a virtualized table using react-virtuoso. The table renders only the visible rows, which improves performance when dealing with large datasets.

```jsx
import React from 'react';
import { TableVirtuoso } from 'react-virtuoso';

const App = () => (
  <TableVirtuoso
    data={Array.from({ length: 1000 }, (_, index) => ({ id: index, name: `Item ${index}` }))}
    columns={[{ key: 'id', label: 'ID' }, { key: 'name', label: 'Name' }]}
    itemContent={(index, item) => (
      <tr>
        <td>{item.id}</td>
        <td>{item.name}</td>
      </tr>
    )}
  />
);

export default App;
```

Other packages similar to react-virtuoso

react-window

react-window is a lightweight library for rendering large lists and tabular data. It provides similar functionality to react-virtuoso but with a smaller API surface. It is highly performant and easy to use, but may require more manual setup for advanced use cases.

react-virtualized

react-virtualized is a comprehensive library for rendering large lists, tables, and grids. It offers a wide range of features and customization options, making it suitable for complex use cases. However, it has a steeper learning curve compared to react-virtuoso.

react-infinite-scroll-component

react-infinite-scroll-component is a simple library for implementing infinite scrolling in React applications. It is less feature-rich compared to react-virtuoso but is easy to set up and use for basic infinite scrolling needs.

README

React Virtuoso is the most powerful React virtual list/table component, full stop. Here's why:

• Variable sized items out of the box; no manual measurements or hard-coding item heights is necessary;
• Support for reverse (bottom up) scrolling and prepending items (chat, feeds, etc);
• Grouped mode with sticky headers;
• Responsive grid layout;
• Table Support;
• Automatic handling of content resize;
• Custom Header, Footer, and empty list components;
• Pinned top items;
• Endless scrolling, press to load more;
• Initial top most item index;
• Scroll to index method.

For live examples and documentation, check the documentation website.

Sponsors

If you are using Virtuoso for work, sponsor it. Any donation helps a lot with the project development and maintenance.

Get Started

npm install react-virtuoso

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

const App = () => {
  return <Virtuoso style={{ height: '400px' }} totalCount={200} itemContent={index => <div>Item {index}</div>} />
}

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

Grouped Mode

The GroupedVirtuoso component is a variant of the "flat" Virtuoso, with the following differences:

• Instead of totalCount, the component exposes groupCounts: number[] property, 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 itemContent property, the component requires an additional groupContent property, which renders the group header. The groupContent callback receives the zero-based group index as a parameter.

Grid

The VirtuosoGrid component displays same sized items in multiple columns. The layout and item sizing is controlled through CSS class properties, which allows you to use media queries, min-width, percentage, etc.

Table

The TableVirtuoso component works just like Virtuoso, but with HTML tables. It supports window scrolling, sticky headers, sticky columns, and works with React Table and MUI Table.

Works With Your UI Library of Choice

You can customize the markup up to your requirements - check the Material UI list demo. If you need to support reordering, check the React Sortable HOC example.

Documentation and Demos

For in-depth documentation and live examples of the supported features and live demos, check the documentation website.

Browser support

To support legacy browsers, you might have to load a ResizeObserver Polyfill before using react-virtuoso:

import ResizeObserver from 'resize-observer-polyfill'
if (!window.ResizeObserver)
  window.ResizeObserver = ResizeObserver

Author

Petyo Ivanov @petyosi.

Contributing

Fixes and new Features

To run the tests, use npm run test. An end-to-end browser-based test suite is runnable with npm run e2e, with the pages being e2e/*.tsx and the tests e2e/*.test.ts.

A convenient way to debug something is to preview the test cases in the browser. To do that, run npm run browse-examples - it will open a crude UI that lets you browse the components in the e2e folder.

Docs

The documentation site is built with docusaurus and the content is available in the site/docs directory. The API reference is generated from the doc comments in src/components.tsx.

License

MIT License.