VirtualList

A headless virtualized list for rendering large flat datasets. Supports keyboard navigation, infinite scroll, and live prepend with scroll anchoring.

Basic Usage

500 items

Render a virtualized list with the useVirtualList hook or VirtualList component:

import { useVirtualList } from 'virtualized-ui';

const { virtualItems, totalSize, containerRef, measureElement } =
  useVirtualList({
    data,
    getItemId: (item) => item.id,
    estimatedItemHeight: 80,
  });

Or use the component API:

import { VirtualList } from 'virtualized-ui';

<VirtualList
  data={items}
  getItemId={(item) => item.id}
  height={400}
  renderItem={({ item, index }) => (
    <div>{item.title}</div>
  )}
/>

Option	Type	Default
`data`	`TData[]`	required
`getItemId`	`(item, i) => string`	required
`estimatedItemHeight`	`number`	100
`overscan`	`number`	5
`gap`	`number`	0

Features

Infinite Scroll

Load more data on scroll

Keyboard Navigation

Arrow keys, Home/End

Live Updates

Prepend items with scroll anchoring

Social Feed

Full combined demo

Return Values (Hook)

const {
  virtualizer,      // TanStack Virtual instance
  virtualItems,     // Currently visible virtual items
  totalSize,        // Total scrollable height (px)
  containerRef,     // Ref for scroll container
  handleScroll,     // Scroll handler (for infinite scroll)
  handleKeyDown,    // Keyboard handler
  setFocusedItem,   // (index) => void
  focusedIndex,     // Current focused index
  scrollToIndex,    // (index) => void
  scrollToTop,      // () => void
  measureElement,   // Ref callback for dynamic sizing
  data,             // The data array
} = useVirtualList(options);