tessl/npm-rc-virtual-list

React Virtual List Component which worked with animation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

RC Virtual List

Name: tessl/npm-rc-virtual-list
Author: tessl

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';

Install with Tessl CLI