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

List Component

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

The main virtualized list component providing efficient rendering for large datasets through viewport-based virtualization.

Capabilities

List Component

The primary React component that renders virtualized lists with automatic optimization.

/**
 * Main virtual list component with full virtualization support
 * @param props - List configuration and data
 * @returns Virtualized list React element
 */
const List: <Item = any>(
  props: ListProps<Item> & { ref?: React.Ref<ListRef> }
) => React.ReactElement;

interface ListProps<T> extends Omit<React.HTMLAttributes<any>, 'children'> {
  /** CSS class prefix for styling */
  prefixCls?: string;
  /** Render function for each list item */
  children: RenderFunc<T>;
  /** Array of data items to render */
  data: T[];
  /** Container height in pixels - required for virtualization */
  height?: number;
  /** Minimum height of each item in pixels */
  itemHeight?: number;
  /** If true, uses height; if false, uses maxHeight */
  fullHeight?: boolean;
  /** Key extraction function or property name for item identification */
  itemKey: React.Key | ((item: T) => React.Key);
  /** Custom container component (default: 'div') */
  component?: string | React.FC<any> | React.ComponentClass<any>;
  /** Enable/disable virtualization (default: true when height/itemHeight provided) */
  virtual?: boolean;
  /** Text direction for RTL support */
  direction?: ScrollBarDirectionType;
  /** Enable horizontal scrolling with specified scroll width */
  scrollWidth?: number;
  /** Custom styles for scrollbars */
  styles?: {
    horizontalScrollBar?: React.CSSProperties;
    horizontalScrollBarThumb?: React.CSSProperties;
    verticalScrollBar?: React.CSSProperties;
    verticalScrollBarThumb?: React.CSSProperties;
  };
  /** Control scrollbar visibility */
  showScrollBar?: boolean | 'optional';
  /** Native scroll event handler */
  onScroll?: React.UIEventHandler<HTMLElement>;
  /** Virtual scroll position callback */
  onVirtualScroll?: (info: ScrollInfo) => void;
  /** Callback when visible items change */
  onVisibleChange?: (visibleList: T[], fullList: T[]) => void;
  /** Props passed to inner container for accessibility */
  innerProps?: InnerProps;
  /** Custom content renderer for advanced use cases */
  extraRender?: (info: ExtraRenderInfo) => React.ReactNode;
}

Usage Examples:

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

// Basic virtualized list
const BasicList = () => {
  const data = Array.from({ length: 1000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
  
  return (
    <List
      data={data}
      height={300}
      itemHeight={40}
      itemKey="id"
    >
      {(item) => <div>{item.text}</div>}
    </List>
  );
};

// Custom component with styling
const StyledList = () => {
  const data = [/* ... */];
  
  return (
    <List
      component="ul"
      className="my-list"
      data={data}
      height={400}
      itemHeight={50}
      itemKey="id"
      styles={{
        verticalScrollBar: { background: '#f0f0f0' },
        verticalScrollBarThumb: { background: '#666' }
      }}
    >
      {(item) => <li>{item.name}</li>}
    </List>
  );
};

// With scroll callbacks
const CallbackList = () => {
  const handleVirtualScroll = (info) => {
    console.log('Virtual scroll position:', info.x, info.y);
  };
  
  const handleVisibleChange = (visibleItems, allItems) => {
    console.log(`Showing ${visibleItems.length} of ${allItems.length} items`);
  };
  
  return (
    <List
      data={data}
      height={300}
      itemHeight={40}
      itemKey="id"
      onVirtualScroll={handleVirtualScroll}
      onVisibleChange={handleVisibleChange}
    >
      {(item) => <div>{item.content}</div>}
    </List>
  );
};

Render Function

Function that renders individual list items with positioning information.

/**
 * Function for rendering individual list items
 * @param item - The data item to render
 * @param index - Index of the item in the data array
 * @param props - Additional properties including style and offset information
 * @returns React node to render
 */
type RenderFunc<T> = (
  item: T,
  index: number,
  props: { 
    style: React.CSSProperties; 
    offsetX: number;
  }
) => React.ReactNode;

The render function receives three parameters:

item: The actual data item from the data array
index: The position of the item in the array
props.style: CSS styles for proper positioning (important for virtualization)
props.offsetX: Horizontal offset for horizontal scrolling scenarios

Scroll Direction Type

type ScrollBarDirectionType = 'ltr' | 'rtl';

Inner Props Interface

interface InnerProps {
  [key: string]: any;
}

Used to pass additional props to the inner container element, primarily for accessibility attributes like aria-* properties.

Performance Considerations

itemHeight: Providing accurate itemHeight improves initial rendering performance
itemKey: Use stable, unique keys to optimize re-rendering
virtual: Can be disabled for small lists to avoid virtualization overhead
data: Avoid recreating the data array on each render to prevent unnecessary updates