Virtual List

High-performance virtual list hook for React. Efficiently renders large lists by only rendering visible items.

Installation

npm install @windowing-kit/virtual-list
# or
pnpm add @windowing-kit/virtual-list
# or
yarn add @windowing-kit/virtual-list

Quick Start

import { useVirtualList } from "@windowing-kit/virtual-list";

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

  const { containerRef, listHeight, virtualItems } = useVirtualList({
    itemHeight: 50,
    items,
    overscan: 3,
  });

  return (
    <div
      ref={containerRef}
      style={{
        height: "400px",
        overflow: "auto",
      }}
    >
      <div style={{ height: listHeight, position: "relative" }}>
        {virtualItems.map((virtualItem) => (
          <div
            key={virtualItem.index}
            style={{
              position: "absolute",
              top: virtualItem.offsetY,
              height: 50,
              width: "100%",
            }}
          >
            {virtualItem.data.name}
          </div>
        ))}
      </div>
    </div>
  );
}

API

useVirtualList<T>(options)

Virtual list hook.

Options

Property	Type	Required	Default	Description
itemHeight	number	Yes	-	Height of each item in pixels
items	T[]	Yes	-	Array of items to render
overscan	number	No	3	Number of items to render outside the viewport

Return

Property	Type	Description
containerRef	(element: HTMLElement | null) => void	Ref callback to attach to the scroll container
listHeight	number	Total height of the list in pixels
virtualItems	VirtualItem<T>[]	Array of virtual items currently visible in the viewport

VirtualItem<T>

Each virtual item has the following properties:

Property	Type	Description
index	number	Index in the original array
offsetY	number	Y offset in pixels within the list
data	T	Original item data

Examples

Basic Usage

import { useVirtualList } from "@windowing-kit/virtual-list";

function TodoList({ todos }) {
  const { containerRef, listHeight, virtualItems } = useVirtualList({
    itemHeight: 60,
    items: todos,
    overscan: 5,
  });

  return (
    <div ref={containerRef} style={{ height: "500px", overflow: "auto" }}>
      <div style={{ height: listHeight, position: "relative" }}>
        {virtualItems.map((virtualItem) => (
          <div
            key={virtualItem.index}
            style={{
              position: "absolute",
              top: virtualItem.offsetY,
              height: 60,
              width: "100%",
              padding: "10px",
              borderBottom: "1px solid #eee",
            }}
          >
            {virtualItem.data.title}
          </div>
        ))}
      </div>
    </div>
  );
}

With Custom Styling

function StyledList({ items }) {
  const { containerRef, listHeight, virtualItems } = useVirtualList({
    itemHeight: 80,
    items,
  });

  return (
    <div
      ref={containerRef}
      className="scroll-container"
      style={{ height: "600px", overflow: "auto" }}
    >
      <div style={{ height: listHeight, position: "relative" }}>
        {virtualItems.map((virtualItem) => (
          <div
            key={virtualItem.index}
            className="list-item"
            style={{
              position: "absolute",
              top: virtualItem.offsetY,
              height: 80,
              width: "100%",
            }}
          >
            <h3>{virtualItem.data.title}</h3>
            <p>{virtualItem.data.description}</p>
          </div>
        ))}
      </div>
    </div>
  );
}