lite-virtualized-list

A React component library for rendering large lists efficiently using virtualization techniques. It provides a simple and customizable API for developers to create performant list components that can handle thousands of items without sacrificing user experience.

Features

• Virtualization - Only renders visible items for maximum performance
• Dynamic Heights - Automatically handles items with variable heights
• TypeScript - Full TypeScript support with generic types
• Overscan - Configurable overscan for smooth scrolling experience
• Memoization - Fine-grained memoization prevents unnecessary re-renders

Installation

npm install lite-virtualized-list
# or
bun add lite-virtualized-list

Quick Start

see demo

API

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | data | T[] | ✅ | - | Array of items to render | | itemHeight | number | ✅ | - | Estimated height of each item in pixels | | renderItem | (item: T, index: number) => ReactNode | ✅ | - | Render function for each item | | keyExtractor | (item: T, index: number) => React.Key | - | index | Function to extract item key | | overscan | number | - | 5 | Number of extra items to render outside viewport | | className | string | - | '' | CSS class for container | | style | CSSProperties | - | {} | Inline styles for container | | extraData | unknown | - | - | Extra data to trigger re-renders | | onScroll | (e: UIEvent) => void | - | - | Scroll event callback | | onEndReached | () => void | - | - | Callback when scrolled to end | | onEndReachedThreshold | number | - | 100 | Threshold in pixels from end to trigger onEndReached | | initialItemCount | number | - | - | Number of items to render on initial mount (for better perceived performance and SSR) |

Ref Methods

Use a component ref to call imperative scrolling methods:

| Method | Type | Description | |------|------|-------------| | scrollToIndex | (index: number) => void | Scroll to a zero-based item index | Example:

listRef.current?.scrollToIndex(500);