or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

component-handles.mdgrid-virtualization.mdgrouped-lists.mdindex.mdlist-virtualization.mdtable-virtualization.md
tile.json

tessl/npm-react-virtuoso

A virtual scroll React component for efficiently rendering large scrollable lists, grids, tables, and feeds

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-virtuoso@4.14.x

To install, run

npx @tessl/cli install tessl/npm-react-virtuoso@4.14.0

index.mddocs/

React Virtuoso

React Virtuoso is a comprehensive virtualization library for React that provides components for efficiently rendering large scrollable lists, grids, and tables. It automatically handles variable item sizes, supports grouping with sticky headers, offers responsive grid layouts, and includes specialized table virtualization—all without manual size calculations or complex configuration.

Package Information

  • Package Name: react-virtuoso
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install react-virtuoso

Core Imports

import { 
  Virtuoso, 
  GroupedVirtuoso, 
  VirtuosoGrid, 
  TableVirtuoso, 
  GroupedTableVirtuoso 
} from "react-virtuoso";

For specific components:

import { Virtuoso } from "react-virtuoso";
import type { VirtuosoHandle, VirtuosoProps } from "react-virtuoso";

CommonJS:

const { Virtuoso, VirtuosoGrid, TableVirtuoso } = require("react-virtuoso");

Basic Usage

import React from "react";
import { Virtuoso } from "react-virtuoso";

// Simple list virtualization
function MyList() {
  const items = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);
  
  return (
    <Virtuoso
      style={{ height: '400px' }}
      data={items}
      itemContent={(index, item) => (
        <div style={{ padding: '10px' }}>
          {item}
        </div>
      )}
    />
  );
}

// Grid virtualization  
import { VirtuosoGrid } from "react-virtuoso";

function MyGrid() {
  return (
    <VirtuosoGrid
      style={{ height: '400px' }}
      totalCount={10000}
      itemContent={(index) => (
        <div style={{ padding: '10px', backgroundColor: '#f0f0f0' }}>
          Item {index}
        </div>
      )}
    />
  );
}

// Table virtualization
import { TableVirtuoso } from "react-virtuoso";

function MyTable() {
  const users = Array.from({ length: 10000 }, (_, i) => ({
    id: i,
    name: `User ${i}`,
    email: `user${i}@example.com`
  }));

  return (
    <TableVirtuoso
      style={{ height: '400px' }}
      data={users}
      fixedHeaderContent={() => (
        <tr>
          <th>Name</th>
          <th>Email</th>
        </tr>
      )}
      itemContent={(index, user) => (
        <>
          <td>{user.name}</td>
          <td>{user.email}</td>
        </>
      )}
    />
  );
}

Architecture

React Virtuoso is built around several key concepts:

  • Virtualization Core: Smart rendering system that only renders visible items plus a configurable buffer
  • Size Calculation: Automatic item size detection with optional fixed or default height optimization
  • Scroll Management: Advanced scroll handling with smooth scrolling, scroll-to-item, and follow-output capabilities
  • Component System: Pluggable component architecture allowing full customization of rendered elements
  • State Management: Internal state preservation and restoration for navigation scenarios
  • Performance Features: Scroll seek mode for fast scrolling, overscan configuration, and scroll parent customization

Capabilities

List Virtualization

Core list virtualization component that handles variable-sized items automatically. Supports infinite scrolling, custom components, and advanced scroll behaviors.

function Virtuoso<D = any, C = any>(props: VirtuosoProps<D, C>): JSX.Element;

interface VirtuosoProps<D, C> {
  data?: readonly D[];
  totalCount?: number;
  itemContent?: ItemContent<D, C>;
  components?: Components<D, C>;
  fixedItemHeight?: number;
  defaultItemHeight?: number;
  followOutput?: FollowOutput;
  endReached?: (index: number) => void;
  startReached?: (index: number) => void;
}

type ItemContent<D, C> = (index: number, data: D, context: C) => React.ReactNode;

List Virtualization

Grouped Lists

Virtualization component for lists with grouped data and sticky group headers. Perfect for categorized content like contact lists or file browsers.

function GroupedVirtuoso<D = any, C = any>(props: GroupedVirtuosoProps<D, C>): JSX.Element;

interface GroupedVirtuosoProps<D, C> {
  groupCounts?: number[];
  groupContent?: GroupContent<C>;
  itemContent?: GroupItemContent<D, C>;
  firstItemIndex?: number;
}

type GroupContent<C> = (index: number, context: C) => React.ReactNode;
type GroupItemContent<D, C> = (index: number, groupIndex: number, data: D, context: C) => React.ReactNode;

Grouped Lists

Grid Virtualization

Responsive grid virtualization that automatically adapts to container width. Ideal for image galleries, card layouts, and masonry-style interfaces.

function VirtuosoGrid<D = any, C = any>(props: VirtuosoGridProps<D, C>): JSX.Element;

interface VirtuosoGridProps<D, C> {
  data?: readonly D[];
  totalCount?: number;
  itemContent?: GridItemContent<D, C>;
  components?: GridComponents<C>;
  listClassName?: string;
  itemClassName?: string;
}

type GridItemContent<D, C> = (index: number, data: D, context: C) => React.ReactNode;

Grid Virtualization

Table Virtualization

Specialized virtualization for HTML tables with fixed headers and footers. Maintains proper table semantics while virtualizing large datasets.

function TableVirtuoso<D = any, C = any>(props: TableVirtuosoProps<D, C>): JSX.Element;

interface TableVirtuosoProps<D, C> {
  data?: readonly D[];
  itemContent?: ItemContent<D, C>;
  fixedHeaderContent?: FixedHeaderContent;
  fixedFooterContent?: FixedFooterContent;
  components?: TableComponents<D, C>;
}

type FixedHeaderContent = (() => React.ReactNode) | null;
type FixedFooterContent = (() => React.ReactNode) | null;

Table Virtualization

Component Handles and Refs

All virtualization components provide handle interfaces for programmatic control including scrolling, state management, and viewport queries.

interface VirtuosoHandle {
  scrollToIndex(location: FlatIndexLocationWithAlign | number): void;
  scrollIntoView(location: FlatScrollIntoViewLocation): void;
  scrollTo(location: ScrollToOptions): void;
  scrollBy(location: ScrollToOptions): void;
  getState(stateCb: StateCallback): void;
  autoscrollToBottom(): void;
}

interface FlatIndexLocationWithAlign {
  index: number | 'LAST';
  align?: 'start' | 'center' | 'end';
  behavior?: 'auto' | 'smooth';
  offset?: number;
}

Component Handles

Core Types

interface Components<Data = any, Context = any> {
  EmptyPlaceholder?: React.ComponentType<ContextProp<Context>>;
  Footer?: React.ComponentType<ContextProp<Context>>;  
  Header?: React.ComponentType<ContextProp<Context>>;
  Item?: React.ComponentType<ItemProps<Data> & ContextProp<Context>>;
  List?: React.ComponentType<ListProps & ContextProp<Context>>;
  Scroller?: React.ComponentType<ScrollerProps & ContextProp<Context>>;
  ScrollSeekPlaceholder?: React.ComponentType<ScrollSeekPlaceholderProps & ContextProp<Context>>;
}

interface ListRange {
  startIndex: number;
  endIndex: number;
}

interface ContextProp<C> {
  context: C;
}

type ComputeItemKey<D, C> = (index: number, item: D, context: C) => React.Key;

type FollowOutput = FollowOutputCallback | FollowOutputScalarType;
type FollowOutputCallback = (isAtBottom: boolean) => FollowOutputScalarType;
type FollowOutputScalarType = 'auto' | 'smooth' | boolean;

Testing & SSR Utilities

For testing and server-side rendering scenarios, React Virtuoso provides mock contexts that allow components to render with predefined dimensions.

interface VirtuosoMockContextValue {
  itemHeight: number;
  viewportHeight: number;
}

interface VirtuosoGridMockContextValue {
  itemHeight: number;
  itemWidth: number;
  viewportHeight: number;
  viewportWidth: number;
}

const VirtuosoMockContext: React.Context<VirtuosoMockContextValue | undefined>;
const VirtuosoGridMockContext: React.Context<VirtuosoGridMockContextValue | undefined>;

Usage Examples:

import { VirtuosoMockContext, Virtuoso } from 'react-virtuoso';

// For SSR or testing environments
function SSRList() {
  return (
    <VirtuosoMockContext.Provider value={{ itemHeight: 50, viewportHeight: 600 }}>
      <Virtuoso
        data={items}
        itemContent={(index, item) => <div>{item}</div>}
      />
    </VirtuosoMockContext.Provider>
  );
}

// Grid mock context
import { VirtuosoGridMockContext, VirtuosoGrid } from 'react-virtuoso';

function SSRGrid() {
  return (
    <VirtuosoGridMockContext.Provider value={{ 
      itemHeight: 200, 
      itemWidth: 250,
      viewportHeight: 600,
      viewportWidth: 800
    }}>
      <VirtuosoGrid
        totalCount={1000}
        itemContent={(index) => <div>Item {index}</div>}
      />
    </VirtuosoGridMockContext.Provider>
  );
}