or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

grid-virtualization.mdimperative-apis.mdindex.mdlist-virtualization.mdtypescript-utilities.md
tile.json

tessl/npm-react-window

High-performance virtualization components for React that render large lists and grids efficiently by only showing visible items

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

To install, run

npx @tessl/cli install tessl/npm-react-window@2.0.0

index.mddocs/

React Window

React Window is a high-performance virtualization library for React applications that enables efficient rendering of large datasets in lists and grids. The library provides two core components - List and Grid - that only render visible items in the viewport, dramatically improving performance when dealing with thousands or millions of data items.

Package Information

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

Core Imports

import { 
  Grid, 
  List, 
  useGridRef, 
  useGridCallbackRef,
  useListRef, 
  useListCallbackRef,
  getScrollbarSize 
} from "react-window";
import type { 
  GridProps, 
  ListProps, 
  GridImperativeAPI, 
  ListImperativeAPI,
  CellComponentProps,
  RowComponentProps,
  Align
} from "react-window";

For CommonJS:

const { 
  Grid, 
  List, 
  useGridRef, 
  useGridCallbackRef,
  useListRef, 
  useListCallbackRef,
  getScrollbarSize 
} = require("react-window");

Basic Usage

List Component

import React from "react";
import { List } from "react-window";

const MyList = () => {
  const items = Array.from({ length: 10000 }, (_, index) => `Item ${index}`);

  const RowComponent = ({ index, style }: { index: number; style: React.CSSProperties }) => (
    <div style={style}>
      {items[index]}
    </div>
  );

  return (
    <List
      rowComponent={RowComponent}
      rowCount={items.length}
      rowHeight={35}
      rowProps={{}}
      style={{ height: 400, width: 300 }}
    />
  );
};

Grid Component

import React from "react";
import { Grid } from "react-window";

const MyGrid = () => {
  const CellComponent = ({ 
    columnIndex, 
    rowIndex, 
    style 
  }: { 
    columnIndex: number; 
    rowIndex: number; 
    style: React.CSSProperties;
  }) => (
    <div style={style}>
      Cell {rowIndex},{columnIndex}
    </div>
  );

  return (
    <Grid
      cellComponent={CellComponent}
      cellProps={{}}
      columnCount={100}
      columnWidth={100}
      rowCount={100}
      rowHeight={50}
      style={{ height: 400, width: 500 }}
    />
  );
};

Architecture

React Window is built around several key components:

  • Virtualization Core: Smart rendering algorithm that calculates visible items and manages DOM efficiently
  • Component System: Grid and List components that handle 2D and 1D data respectively
  • Imperative APIs: Ref-based APIs for programmatic scrolling and element access
  • Type System: Full TypeScript support with generic type preservation for custom props
  • Hook Utilities: Convenience hooks for proper TypeScript ref management

Capabilities

List Virtualization

One-dimensional virtualized scrolling for large lists with support for variable row heights, custom row rendering, and efficient item positioning.

function List<RowProps extends object>(props: ListProps<RowProps>): JSX.Element;

interface ListProps<RowProps extends object> {
  rowComponent: (props: { index: number; style: CSSProperties } & RowProps) => ReactNode;
  rowCount: number;
  rowHeight: number | string | ((index: number, rowProps: RowProps) => number);
  rowProps: RowProps;
  listRef?: Ref<ListImperativeAPI>;
  onRowsRendered?: (args: { startIndex: number; stopIndex: number }) => void;
  onResize?: (size: { height: number; width: number }, prevSize: { height: number; width: number }) => void;
  overscanCount?: number;
  className?: string;
  style?: CSSProperties;
  defaultHeight?: number;
}

List Virtualization

Grid Virtualization

Two-dimensional virtualized scrolling for large grids with support for variable cell sizes, custom cell rendering, and efficient positioning for both rows and columns.

function Grid<CellProps extends object>(props: GridProps<CellProps>): JSX.Element;

interface GridProps<CellProps extends object> {
  cellComponent: (props: { columnIndex: number; rowIndex: number; style: CSSProperties } & CellProps) => ReactNode;
  cellProps: CellProps;
  columnCount: number;
  columnWidth: number | string | ((index: number, cellProps: CellProps) => number);
  rowCount: number;
  rowHeight: number | string | ((index: number, cellProps: CellProps) => number);
  gridRef?: Ref<GridImperativeAPI>;
  onCellsRendered?: (args: { columnStartIndex: number; columnStopIndex: number; rowStartIndex: number; rowStopIndex: number }) => void;
  onResize?: (size: { height: number; width: number }, prevSize: { height: number; width: number }) => void;
  overscanCount?: number;
  className?: string;
  style?: CSSProperties;
  dir?: "ltr" | "rtl";
  defaultHeight?: number;
  defaultWidth?: number;
}

Grid Virtualization

Imperative Scrolling APIs

Programmatic scrolling controls for both List and Grid components with smooth scrolling options and alignment controls.

interface ListImperativeAPI {
  get element(): HTMLDivElement | null;
  scrollToRow(params: { index: number; align?: Align; behavior?: ScrollBehavior }): void;
}

interface GridImperativeAPI {
  get element(): HTMLDivElement | null;
  scrollToCell(params: { rowIndex: number; columnIndex: number; rowAlign?: Align; columnAlign?: Align; behavior?: ScrollBehavior }): void;
  scrollToRow(params: { index: number; align?: Align; behavior?: ScrollBehavior }): void;
  scrollToColumn(params: { index: number; align?: Align; behavior?: ScrollBehavior }): void;
}

Imperative APIs

TypeScript Hook Utilities

Convenience hooks for creating properly typed refs for Grid and List components, supporting both regular refs and callback refs.

function useGridRef(): RefObject<GridImperativeAPI>;
function useGridCallbackRef(): [GridImperativeAPI | null, (instance: GridImperativeAPI | null) => void];
function useListRef(): RefObject<ListImperativeAPI>;
function useListCallbackRef(): [ListImperativeAPI | null, (instance: ListImperativeAPI | null) => void];

TypeScript Utilities

Types

type Align = "auto" | "center" | "end" | "smart" | "start";

interface CellComponentProps<CellProps extends object = object> {
  columnIndex: number;
  rowIndex: number;
  style: CSSProperties;
}

interface RowComponentProps<RowProps extends object = object> {
  index: number;
  style: CSSProperties;
}

Utilities

Scrollbar Size Detection

Utility function for detecting browser scrollbar dimensions, useful for layout calculations.

function getScrollbarSize(recalculate?: boolean): number;