# React Virtuoso — High-Performance Virtual List Component for React

> A React component for rendering large lists and tables with automatic item height measurement and smooth scrolling. Handles variable-height rows, grouped lists, and infinite loading without manual size calculation.

## Install

Save in your project root:

# React Virtuoso — High-Performance Virtual List Component for React

## Quick Use
```bash
npm install react-virtuoso
```
```jsx
import { Virtuoso } from "react-virtuoso";

function Feed() {
  return (
    <Virtuoso
      style={{ height: "400px" }}
      totalCount={10000}
      itemContent={(index) => <div>Item {index}</div>}
    />
  );
}
```

## Introduction
React Virtuoso is a virtualization library for React that renders only the visible portion of large lists, tables, and grids. Unlike many virtualization solutions, it automatically measures item heights, removing the need to specify fixed row sizes and making it suitable for content with unpredictable dimensions like chat feeds and social timelines.

## What React Virtuoso Does
- Renders only visible items in the viewport plus a configurable overscan buffer
- Automatically measures variable-height items without requiring size hints
- Supports grouped lists with sticky headers that pin during scroll
- Provides a TableVirtualoso component for virtualized HTML tables with proper semantics
- Handles reverse scrolling for chat-style interfaces where new items appear at the bottom

## Architecture Overview
React Virtuoso uses a state management kernel that tracks scroll position, viewport dimensions, and measured item sizes. When the user scrolls, the kernel calculates which item range is visible and triggers a re-render of only those items. Item heights are measured after initial render and cached for accurate scroll position calculation. The architecture separates the scroll handling logic from the rendering layer, enabling the same kernel to power lists, tables, and grids.

## Self-Hosting & Configuration
- Install via npm and use the Virtuoso component for lists or TableVirtualoso for tables
- Set totalCount and itemContent to define the data source and render function
- Use endReached callback for infinite scroll pagination
- Configure overscan to balance rendering performance with scroll smoothness
- Customize the scroller, list, and item wrapper components for full styling control

## Key Features
- Zero-configuration variable-height item support with automatic measurement
- Grouped lists with sticky group headers for categorized data
- Reverse scroll mode for chat and messaging interfaces
- Built-in scroll-to-index API with smooth and auto alignment options
- SSR-compatible with initial item count rendering before hydration

## Comparison with Similar Tools
- **react-window** — requires fixed item sizes or a size getter function; React Virtuoso measures automatically
- **react-virtualized** — a larger library with more components; React Virtuoso has a simpler API for common cases
- **TanStack Virtual** — headless virtualizer hook; React Virtuoso provides ready-to-use components
- **Native CSS overflow** — works for small lists but causes performance issues with thousands of items

## FAQ
**Q: Do I need to know item heights in advance?**
A: No. React Virtuoso measures items after rendering. You can optionally provide estimated sizes for better initial scroll position accuracy.

**Q: Can I use it for horizontal lists?**
A: The primary components are vertical. For horizontal virtualization, consider TanStack Virtual or a custom scroll container.

**Q: How does it handle dynamic content that changes height after render?**
A: It re-measures items when content changes. Use the increaseViewportBy prop to render extra items if layout shifts are frequent.

**Q: Does it support window scrolling instead of a scrollable container?**
A: Yes. Pass useWindowScroll={true} to make the list scroll with the browser window instead of a fixed container.

## Sources
- https://github.com/petyosi/react-virtuoso
- https://virtuoso.dev/

---
Source: https://tokrepo.com/en/workflows/asset-5f729e97
Author: AI Open Source