or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdlist-component.mdlist-reference.mdrender-system.mdscrolling.md
tile.json

tessl/npm-rc-virtual-list

React Virtual List Component which worked with animation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/rc-virtual-list@3.19.x

To install, run

npx @tessl/cli install tessl/npm-rc-virtual-list@3.19.0

index.mddocs/

RC Virtual List

RC Virtual List is a high-performance React component for rendering large datasets efficiently through virtualization. It renders only the visible items in the viewport, significantly improving performance and memory usage when displaying thousands of list items, while supporting animations, variable item heights, and custom scrolling behavior.

Package Information

  • Package Name: rc-virtual-list
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install rc-virtual-list
  • Peer Dependencies: React >=16.9.0, React-DOM >=16.9.0

Core Imports

import List from "rc-virtual-list";
import type { ListRef, ListProps } from "rc-virtual-list";

For CommonJS:

const List = require("rc-virtual-list");

Note: Only ListRef and ListProps types are directly exported. Other types like RenderFunc, ScrollInfo, etc. are internal to the package and not available for import.

Basic Usage

import React from "react";
import List from "rc-virtual-list";

const data = Array.from({ length: 10000 }, (_, i) => ({ id: i, name: `Item ${i}` }));

function MyVirtualList() {
  return (
    <List
      data={data}
      height={400}
      itemHeight={50}
      itemKey="id"
    >
      {(item, index) => (
        <div style={{ height: 50, padding: "8px" }}>
          {item.name}
        </div>
      )}
    </List>
  );
}

Architecture

RC Virtual List uses several key architectural patterns:

  • Virtual Scrolling Engine: Only renders items visible in the viewport plus buffer items for smooth scrolling
  • Dynamic Height Calculation: Supports variable item heights with automatic measurement and caching
  • Custom Scrollbar System: Provides styleable scrollbars that work seamlessly with virtualization
  • Animation Integration: Works with React animation libraries through careful lifecycle management
  • Multi-directional Support: Handles both vertical and horizontal scrolling scenarios
  • Touch/Mobile Optimization: Includes specialized handling for touch devices and mobile browsers
  • Accessibility Features: Built-in keyboard navigation and screen reader support

Capabilities

List Component

The main virtualized list component providing efficient rendering for large datasets. Handles automatic virtualization, scroll management, and item lifecycle.

const List: <Item = any>(
  props: ListProps<Item> & { ref?: React.Ref<ListRef> }
) => React.ReactElement;

export interface ListProps<T> extends Omit<React.HTMLAttributes<any>, 'children'> {
  prefixCls?: string;
  children: RenderFunc<T>;
  data: T[];
  height?: number;
  itemHeight?: number;
  fullHeight?: boolean;
  itemKey: React.Key | ((item: T) => React.Key);
  component?: string | React.FC<any> | React.ComponentClass<any>;
  virtual?: boolean;
  direction?: ScrollBarDirectionType;
  scrollWidth?: number;
  styles?: {
    horizontalScrollBar?: React.CSSProperties;
    horizontalScrollBarThumb?: React.CSSProperties;
    verticalScrollBar?: React.CSSProperties;
    verticalScrollBarThumb?: React.CSSProperties;
  };
  showScrollBar?: boolean | 'optional';
  onScroll?: React.UIEventHandler<HTMLElement>;
  onVirtualScroll?: (info: ScrollInfo) => void;
  onVisibleChange?: (visibleList: T[], fullList: T[]) => void;
  innerProps?: InnerProps;
  extraRender?: (info: ExtraRenderInfo) => React.ReactNode;
}

List Component

List Reference Interface

Programmatic control interface for the List component, providing scroll control and state access.

export interface ListRef {
  nativeElement: HTMLDivElement;
  scrollTo: ScrollTo;
  getScrollInfo: () => ScrollInfo;
}

export type ScrollTo = (arg?: number | ScrollConfig | null) => void;

export interface ScrollInfo {
  x: number;
  y: number;
}

export type ScrollConfig = ScrollTarget | ScrollPos;

List Reference

Type System

Internal type definitions used by the List component (not directly exportable).

// Internal type used by ListProps.children
type RenderFunc<T> = (
  item: T,
  index: number,
  props: { style: React.CSSProperties; offsetX: number }
) => React.ReactNode;

// Internal type used by ListProps.direction
type ScrollBarDirectionType = 'ltr' | 'rtl';

// Internal type used by ListProps.onVirtualScroll
interface ScrollInfo {
  x: number;
  y: number;
}

Render System

Scrolling & Navigation

Advanced scrolling capabilities including programmatic navigation, scroll callbacks, and positioning options.

export type ScrollAlign = 'top' | 'bottom' | 'auto';

export interface ScrollPos {
  left?: number;
  top?: number;
}

export type ScrollTarget = 
  | { index: number; align?: ScrollAlign; offset?: number; }
  | { key: React.Key; align?: ScrollAlign; offset?: number; };

Scrolling

Main Exports

// Default export - the main List component
export default List: <Item = any>(
  props: ListProps<Item> & { ref?: React.Ref<ListRef> }
) => React.ReactElement;

// Named exports - type interfaces only
export type { ListRef, ListProps };

interface ListRef {
  nativeElement: HTMLDivElement;
  scrollTo: (arg?: number | ScrollConfig | null) => void;
  getScrollInfo: () => ScrollInfo;
}

interface ListProps<T> extends Omit<React.HTMLAttributes<any>, 'children'> {
  // See List Component documentation for complete props interface
}

// Internal supporting types (not exported)
interface ScrollInfo {
  x: number;
  y: number;
}

type ScrollConfig = ScrollTarget | ScrollPos;
type ScrollTarget = 
  | { index: number; align?: ScrollAlign; offset?: number; }
  | { key: React.Key; align?: ScrollAlign; offset?: number; };
interface ScrollPos {
  left?: number;
  top?: number;
}
type ScrollAlign = 'top' | 'bottom' | 'auto';