Component
VirtualList
Renders only the visible window of a large list, keeping the DOM small for huge backlogs. Supports variable item heights and horizontal orientation.
Install
Run the CLI to copy the source into your project.
pnpm dlx @stalk-ui/cli add @stalk-ui/virtual-listExamples
Live previews render through the docs app's PandaCSS codegen.
<VirtualListDemo />
Props
Public component props extracted from the source TypeScript types.
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `items` | `readonly TItem[]` | Yes | - | The full backlog. Only the visible window (plus overscan) is ever in the DOM. |
| `estimateSize` | `(index: number) => number` | Yes | - | Estimated item size in px for the flat \`index\`; refined by real measurement. |
| `overscan` | `number` | No | - | Extra items rendered beyond the viewport to smooth fast scrolls (default 8). |
| `horizontal` | `boolean` | No | - | Scroll/lay out along the inline axis instead of the block axis. |
| `gap` | `number` | No | - | Gap in px between items. |
| `getItemKey` | `(item: TItem, index: number) => number \ | string` | No | - |
| `children` | `(item: TItem, virtualItem: VirtualItem) => ReactNode` | Yes | - | Render one item — wrap the return in \`<VirtualList.Item>\`. |
| Prop | Type | Required | Default | Description |
| `virtualItem` | `VirtualItem` | Yes | - | The \`VirtualItem\` handed to the render callback; positions and measures the row. |
Variants
Variant axes exposed by the underlying PandaCSS recipe or slot recipe.
| Variant | Values |
|---|---|
| `orientation` | `vertical`, `horizontal` |
Registry
Files this component contributes to your registry install.
- Manifest: `/r/virtual-list.json`
- Recipe: `virtualList`
- Files: `src/components/ui/virtual-list.tsx`