virtual

🤖 Headless UI for Virtualizing Large Element Lists in JS/TS, React, Solid, Vue and Svelte

5,365

290

5,365

View on GitHub View on NPM

Top Related Projects

react-window

15,727

React components for efficiently rendering large lists and tabular data

react-virtuoso

5,147

The most powerful virtual list component for React

Quick Overview

TanStack/virtual is a headless UI library for efficiently rendering large lists and tables with virtualization. It provides a powerful and flexible solution for handling massive datasets in web applications, ensuring smooth scrolling and optimal performance.

Pros

Highly performant, capable of rendering thousands of rows with minimal impact on performance
Framework-agnostic, can be used with React, Vue, Solid, or vanilla JavaScript
Supports both fixed and variable height rows
Offers advanced features like sticky rows and columns

Cons

Requires a learning curve to understand and implement effectively
May introduce complexity for simpler use cases where virtualization isn't necessary
Documentation could be more comprehensive for some advanced features
Limited community resources compared to more established libraries

Code Examples

Basic usage with React:

import { useVirtualizer } from '@tanstack/react-virtual'

function VirtualList() {
  const parentRef = React.useRef()

  const rowVirtualizer = useVirtualizer({
    count: 10000,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35,
  })

  return (
    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
      <div
        style={{
          height: `${rowVirtualizer.getTotalSize()}px`,
          width: '100%',
          position: 'relative',
        }}
      >
        {rowVirtualizer.getVirtualItems().map((virtualRow) => (
          <div
            key={virtualRow.index}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              height: `${virtualRow.size}px`,
              transform: `translateY(${virtualRow.start}px)`,
            }}
          >
            Row {virtualRow.index}
          </div>
        ))}
      </div>
    </div>
  )
}

Variable size rows:

const rowVirtualizer = useVirtualizer({
  count: 10000,
  getScrollElement: () => parentRef.current,
  estimateSize: (index) => (index % 2 === 0 ? 25 : 50),
  overscan: 5,
})

Sticky header:

{rowVirtualizer.getVirtualItems().map((virtualRow) => (
  <div
    key={virtualRow.index}
    style={{
      position: 'absolute',
      top: 0,
      left: 0,
      width: '100%',
      height: `${virtualRow.size}px`,
      transform: `translateY(${virtualRow.start}px)`,
    }}
  >
    {virtualRow.index === 0 ? (
      <div style={{ position: 'sticky', top: 0, background: 'white' }}>
        Header
      </div>
    ) : (
      `Row ${virtualRow.index}`
    )}
  </div>
))}

Getting Started

Install the package:
```
npm install @tanstack/react-virtual
```

Import and use the useVirtualizer hook in your React component:

import { useVirtualizer } from '@tanstack/react-virtual'

function MyVirtualList() {
  const parentRef = React.useRef()
  const virtualizer = useVirtualizer({
    count: 1000,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35,
  })

  // Implement your virtual list using the virtualizer
}

Refer to the documentation for more advanced usage and configuration options.

Competitor Comparisons

react-window

15,727

React components for efficiently rendering large lists and tabular data

Pros of react-window

More mature and widely adopted in the React ecosystem
Extensive documentation and community support
Simpler API for basic use cases

Cons of react-window

Less flexible for complex layouts and non-uniform item sizes
Limited to React applications only
Fewer built-in features for advanced virtualization scenarios

Code Comparison

react-window:

import { FixedSizeList } from 'react-window';

const Example = () => (
  <FixedSizeList
    height={400}
    itemCount={1000}
    itemSize={35}
    width={300}
  >
    {({ index, style }) => <div style={style}>Row {index}</div>}
  </FixedSizeList>
);

virtual:

import { useVirtualizer } from '@tanstack/react-virtual';

const Example = () => {
  const virtualizer = useVirtualizer({
    count: 1000,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35,
  });

  return (
    <div ref={parentRef}>
      {virtualizer.getVirtualItems().map((virtualRow) => (
        <div key={virtualRow.index} style={virtualRow.style}>
          Row {virtualRow.index}
        </div>
      ))}
    </div>
  );
};

Both libraries provide efficient virtualization for large lists, but virtual offers more flexibility and framework-agnostic usage, while react-window has a simpler API for basic React use cases.

react-virtuoso

5,147

The most powerful virtual list component for React

Pros of react-virtuoso

Simpler API with fewer configuration options, making it easier to get started
Built-in support for grouped lists and grid layouts
Better out-of-the-box performance for large datasets

Cons of react-virtuoso

Less flexible for advanced customization scenarios
Limited support for horizontal virtualization
Smaller community and ecosystem compared to TanStack Virtual

Code Comparison

react-virtuoso:

<Virtuoso
  style={{ height: '400px' }}
  totalCount={1000}
  itemContent={index => <div>Item {index}</div>}
/>

TanStack Virtual:

const { getVirtualItems } = useVirtual({
  count: 1000,
  estimateSize: () => 35,
})

return (
  <div style={{ height: '400px', overflow: 'auto' }}>
    {getVirtualItems().map(virtualItem => (
      <div key={virtualItem.index}>Item {virtualItem.index}</div>
    ))}
  </div>
)

Both libraries offer efficient virtualization for large lists, but react-virtuoso provides a more straightforward implementation with fewer lines of code. TanStack Virtual offers more granular control over the virtualization process, which can be beneficial for complex use cases but requires more setup code.