React Virtuoso

React Virtuoso is a family of React components for virtualized rendering of large scrollable datasets. It renders only the items currently in the viewport, keeping the DOM small and scrolling smooth even with hundreds of thousands of rows. Unlike most virtualization libraries, it handles variable and dynamically-changing item sizes automatically — no manual measurement or hard-coded heights required.

The package ships flat lists (Virtuoso), grouped lists with sticky headers (GroupedVirtuoso), responsive grids (VirtuosoGrid), and virtualized HTML tables (TableVirtuoso), plus first-class support for endless scrolling, pinned items, and scroll-to-index. It has zero runtime dependencies and works with React 16 through 19.

What You Get

• Four components covering the common cases: Virtuoso (flat lists), GroupedVirtuoso (sticky group headers), VirtuosoGrid (responsive grids), and TableVirtuoso (HTML tables)
• Automatic variable-size handling with ResizeObserver — no manual measurement or fixed row heights
• Endless scrolling with startReached/endReached callbacks, press-to-load-more, and scroll-position retention when prepending items
• Imperative controls for scroll-to-index, initial top-most item, and pinned header/footer items
• Full TypeScript types and SSR support, with zero runtime dependencies

Common Use Cases

• Infinite-scroll feeds and timelines that load more data as the user reaches the end
• Chat and messaging interfaces where new messages arrive and older history is loaded on scroll
• Large data tables and grids that must stay responsive with tens of thousands of rows
• Image galleries and product listings rendered in responsive virtualized grids

Under The Hood

Architecture - The library is built on an internal reactive dataflow engine (src/urx and src/react-urx) in which each concern — sizing, scrolling, grouping, initial index, window scrolling — is expressed as a self-contained “system” of input/output streams wired together in a dependency graph (see the many *System.ts files such as listSystem.ts, sizeSystem.ts, and scrollToIndexSystem.ts). The React components (Virtuoso.tsx, VirtuosoGrid.tsx, TableVirtuoso.tsx) are thin shells that bind props to these systems and render the computed visible range. Item offsets and size ranges are stored in a balanced AA-tree (src/AATree.ts) so lookups and range queries stay logarithmic even with hundreds of thousands of rows.

Tech Stack - Written almost entirely in TypeScript (~98% of the codebase). It builds with Vite, tests with Vitest and Playwright for end-to-end scenarios, and lints/formats with oxlint and oxfmt. It carries zero runtime dependencies and declares React and React-DOM (16–19) as peer dependencies, shipping both ESM and CJS bundles with type declarations. The repo is a pnpm workspace monorepo that also houses sibling packages (message-list, masonry, gurx, data-table).

Code Quality - The package is well tested: over a dozen unit test files under test/ cover the sizing, grid, grouped-list, and scroll-to-index systems and SSR, alongside Playwright e2e suites in e2e/. Types are strict and the reactive systems are documented with extensive doc comments. Concerns are cleanly separated into single-responsibility system modules, which keeps the otherwise complex virtualization logic navigable.

API Design - The public surface is deliberately small and ergonomic: pass totalCount and an itemContent render callback and the component handles the rest, with sensible variants for grouped, grid, and table layouts. Naming is consistent (GroupedVirtuoso, VirtuosoGrid, TableVirtuoso), imperative needs are exposed through a ref handle, and the extensive documentation site at virtuoso.dev provides live examples for nearly every feature, keeping the getting-started boilerplate to a few lines.