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 Reference

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

Programmatic control interface for the List component, providing access to scroll functions and current state information.

Capabilities

List Reference Interface

The ref interface provides programmatic control over the list component.

/**
 * Reference interface for programmatic List control
 */
interface ListRef {
  /** Direct access to the native DOM element */
  nativeElement: HTMLDivElement;
  /** Function to programmatically scroll the list */
  scrollTo: (arg?: number | ScrollConfig | null) => void;
  /** Get current scroll position information */
  getScrollInfo: () => ScrollInfo;
}

// Supporting type definitions
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';

Usage Example:

import React, { useRef } from "react";
import List, { type ListRef } from "rc-virtual-list";

const ControlledList = () => {
  const listRef = useRef<ListRef>(null);
  
  const scrollToTop = () => {
    listRef.current?.scrollTo(0);
  };
  
  const scrollToItem = () => {
    listRef.current?.scrollTo({ index: 50, align: 'top' });
  };
  
  const getScrollPosition = () => {
    const info = listRef.current?.getScrollInfo();
    console.log('Current position:', info?.x, info?.y);
  };
  
  return (
    <div>
      <button onClick={scrollToTop}>Scroll to Top</button>
      <button onClick={scrollToItem}>Scroll to Item 50</button>
      <button onClick={getScrollPosition}>Get Position</button>
      
      <List
        ref={listRef}
        data={data}
        height={300}
        itemHeight={40}
        itemKey="id"
      >
        {(item) => <div>{item.name}</div>}
      </List>
    </div>
  );
};

Scroll Function

The scrollTo method accepts various argument types for different scrolling behaviors.

Scroll by pixel position:

// Scroll to specific Y position
listRef.current.scrollTo(500);

// Scroll to top
listRef.current.scrollTo(0);
listRef.current.scrollTo(null);

Scroll Information

The getScrollInfo() method returns the current scroll position with x and y coordinates.

Scroll Position Configuration

/**
 * Scroll to specific coordinates
 */
interface ScrollPos {
  /** Target horizontal position */
  left?: number;
  /** Target vertical position */
  top?: number;
}

Usage Example:

// Scroll to specific coordinates
listRef.current.scrollTo({ left: 100, top: 200 });

// Scroll only vertically
listRef.current.scrollTo({ top: 300 });

// Scroll only horizontally (when scrollWidth is set)
listRef.current.scrollTo({ left: 150 });

Scroll Target Configuration

/**
 * Scroll to specific item by index or key
 */
type ScrollTarget = 
  | {
      /** Target item index */
      index: number;
      /** Alignment of the target item in viewport */
      align?: ScrollAlign;
      /** Additional pixel offset from aligned position */
      offset?: number;
    }
  | {
      /** Target item key */
      key: React.Key;
      /** Alignment of the target item in viewport */
      align?: ScrollAlign;
      /** Additional pixel offset from aligned position */
      offset?: number;
    };

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

Usage Examples:

// Scroll to item by index
listRef.current.scrollTo({ index: 100 });
listRef.current.scrollTo({ index: 100, align: 'top' });
listRef.current.scrollTo({ index: 100, align: 'bottom' });
listRef.current.scrollTo({ index: 100, align: 'auto' }); // Smart alignment

// Scroll to item by key
listRef.current.scrollTo({ key: 'item-42', align: 'top' });

// With offset
listRef.current.scrollTo({ index: 50, align: 'top', offset: 20 });

Scroll Alignment Options

'top': Align the target item to the top of the viewport
'bottom': Align the target item to the bottom of the viewport
'auto': Smart alignment - uses the shortest scroll distance

Native Element Access

The nativeElement property provides direct access to the underlying DOM element:

// Access DOM element
const element = listRef.current.nativeElement;

// Add event listeners
element.addEventListener('scroll', handleScroll);

// Get DOM measurements
const rect = element.getBoundingClientRect();

Install with Tessl CLI