VirtualList

A windowed list that only renders visible items. Use it to efficiently display large datasets without mounting every item in the React tree.

When maxVisible is set, only that many items render at a time. The list auto-scrolls to keep highlightIndex in view. When maxVisible is omitted, all items render with no windowing.

VirtualList is a rendering primitive — it has no focus or keybindings. Parent components handle navigation and pass state down. For an interactive scrollable pane with built-in keybindings, see Viewport.

Two scrolling modes: highlightIndex auto-scrolls to keep a highlighted item in view, while scrollOffset gives direct control over which item appears at the top of the window. Use one or the other, not both.

import { VirtualList } from 'giggles/ui';
import { Text } from 'ink';

function LogViewer({ lines, scrollIndex }: { lines: string[]; scrollIndex: number }) {
  return (
    <VirtualList
      items={lines}
      highlightIndex={scrollIndex}
      maxVisible={20}
      render={({ item, index }) => (
        <Text>
          <Text dimColor>{String(index + 1).padStart(4)} </Text>
          {item}
        </Text>
      )}
    />
  );
}

API Reference

VirtualList

VirtualListRenderProps

Examples

With scrollbar

<VirtualList
  items={items}
  highlightIndex={currentIndex}
  maxVisible={10}
  paginatorStyle="scrollbar"
  render={({ item }) => <Text>{item.label}</Text>}
/>