Virtual List

Virtual list for 100,000 rows. Free, MIT · Data and metrics › Tables

A windowed list: renders only what is on screen, so 100k rows scroll smoothly. Fixed or measured item sizes, optional listbox keyboard model and selection, sticky section headers, and infinite loading at either end (with a stable scroll position when older items are prepended).

Installation

npx valyro-cli@latest add virtual-list

npx shadcn@latest add https://valyro.xyz/r/virtual-list.json

npm install valyro-ui

import 'valyro-ui/styles.css';
import { VirtualList } from 'valyro-ui';

Props

Prop	Type	Default
`items` *	`readonly T[]`		All items; only those near the viewport are rendered.
`renderItem` *	`(item: T, index: number, state: VirtualListItemState) => ReactNode`		Renders one item's content; `state` carries its active, selected and disabled flags in listbox mode.
`getItemKey`	`(item: T, index: number) => Key`	`defaultItemKey`	Stable key per item, used for selection and to keep measured sizes. Defaults to `item.id`, then the index.
`label`	`string`		Accessible name of the list.
`height`	`CSSProperties['height']`	`400`	Height of the scrolling viewport.
`itemSize`	`number`		Every item has this height in px: nothing is measured, which is the fastest mode (100k+ rows).
`estimatedItemSize`	`number`	`48`	Starting guess for measured items (when `itemSize` is not set).
`gap`	`number`	`0`	Space between items, in px.
`padding`	`number`	`0`	Space before the first and after the last item, in px.
`overscan`	`number`	`6`	Items rendered beyond each edge of the viewport.
`selectionMode`	`'none' \| 'single' \| 'multiple'`	`'none'`	`single` / `multiple` turn the list into a listbox with keyboard navigation (arrows, Home/End, Page Up/Down, type-ahead with `getItemText`) and selection. `none` with `onAction` is a navigable listbox without selection; otherwise a plain list.
`selected`	`Key[]`		Controlled `selected`; use with `onSelectedChange`.
`defaultSelected`	`Key[]`	`[]`	Initial `selected` when uncontrolled.
`onSelectedChange`	`(keys: Key[]) => void`		Called with the new `selected` when it changes.
`onAction`	`(item: T, index: number) => void`		Called on Enter or click.
`getItemText`	`(item: T) => string`		Text for type-ahead (listbox mode).
`isItemDisabled`	`(item: T, index: number) => boolean`		Items skipped by keyboard navigation, type-ahead, clicks and selection (listbox mode).
`getSection`	`(item: T, index: number) => string`		Section of an item; consecutive items with the same section get a header. Items must already be in section order.
`renderSectionHeader`	`(section: string) => ReactNode`		Content of a section header. Defaults to the section name.
`stickySectionHeaders`	`boolean`	`true`	Keeps the current section's header pinned to the top.
`sectionHeaderSize`	`number`	`32`	Header height in px when `itemSize` is set (measured otherwise).
`onEndReached`	`() => void`		Called once per item count when the end is within `threshold` px, to load the next page.
`onStartReached`	`() => void`		Called once per item count when the start is within `threshold` px, to load older items (chat).
`threshold`	`number`	`240`	Distance from an end, in px, that counts as reaching it.
`loading`	`boolean \| 'start' \| 'end'`	`false`	Shows a loading row at the end (or at the start while loading older items with `onStartReached`).
`followOutput`	`boolean`	`false`	Starts at the last item and keeps following new ones while scrolled to the end — for chat and logs.
`variant`	`'panel' \| 'plain'`	`'panel'`	`panel` frames the viewport like a card; `plain` leaves it bare for use inside other surfaces.
`dividers`	`boolean`	`false`	Hairlines between items.
`empty`	`ReactNode`		Replaces the default empty state.
`labels`	`Partial<VirtualListLabels>`		Overrides for the built-in English text; keys left out keep their defaults.

Related components

Data Table — Tables with search and sorting
Data Grid — Grid for 100,000 rows: grouping, filters, inline editing
Bulk Action Bar — Actions for selected rows, with keyboard shortcuts
List Block — List with images or icons, descriptions and values
Description List — Key–value list: stacked, inline or a grid with icons
Tree View — Tree structures
Accordion — Collapsible sections
Sortable — Drag-and-drop sorting
JSON Viewer — JSON viewer
Timeline — Event timeline
Card — All-purpose cards
Item Card — Row card: icon, title, description and a control on the right

Previous: Data Grid · Next: Bulk Action Bar · All Data and metrics