# VirtualList

> Renders only visible rows: fixed, measured or externally windowed.

Fixed-height rows; the caller keeps `offset` and updates it from `onScroll`.

- Category: [Data display](https://tarve.dev/docs.md#data)
- Import: `import { VirtualList } from "@tarve/core";`
- Props type: `VirtualListProps<T> | VariableVirtualListProps<T> | WindowedVirtualListProps<T>` (generic)
- Source: [packages/core/src/virtual-list.ts:605](https://github.com/omarcosr/tarve/blob/main/packages/core/src/virtual-list.ts#L605)

## Usage

```tsx title="VirtualList.tsx"
import { Row, Text, VirtualList } from "@tarve/core";

const records = Array.from({ length: 100_000 }, (_, index) => ({ id: index, name: `Record ${index}` }));
let offset = 0;

<VirtualList
  id="records"
  items={records}
  itemHeight={36}
  height={480}
  offset={offset}
  keyForItem={(record) => record.id}
  onScroll={(next) => {
    offset = next;
  }}
  renderItem={(record) => (
    <Row padding={8}>
      <Text>{record.name}</Text>
    </Row>
  )}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly T[]` | — |  |
| `offset` (required) | `number` | — |  |
| `onScroll` (required) | `(offset: number, max: number, info: ScrollInfo) => void` | — | `info.source` tells the user's scrolling from a scrollToItem (and its smooth steps). |
| `renderItem` (required) | `(item: T, index: number) => Child` | — |  |
| `height` | `number` | — | Viewport height in px. Omit it (with an `id`) to fill the parent like `flex: 1`: the list follows its real laid-out height, window resizes included. |
| `itemHeight` | `number` | — |  |
| `keyForItem` | `(item: T, index: number) => string \| number` | — |  |
| `overscan` | `number` | — |  |

### Inherited from `VariableVirtualListProps`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alignment` | `"top" \| "bottom"` | — |  |
| `estimatedItemHeight` | `number` | — |  |
| `followTail` | `boolean` | — |  |
| `id` | `string` | — | Stable list id is required so measured heights survive rerenders. |

### Inherited from `WindowedVirtualListProps`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `itemCount` | `number` | — | Total logical row count; `items` contains only the mounted window. |
| `windowStart` | `number` | — | Logical index represented by `items[0]`. |

## Common props

Shared by every component (descriptions: https://tarve.dev/docs.md#common-props): `children`, `class`, `className`, `highlight`, `id`, `key`, `motionFrom`, `onHighlight`, `onPaste`, `onPointerLeave`, `onPointerMove`, `onSize`, `onTransitionEnd`, `rovingGroup`, `style`.

## Types

```ts title="ScrollInfo"
interface ScrollInfo { source: ScrollSource }
```

Previous: [List](https://tarve.dev/docs/components/List.md) · Next: [Table](https://tarve.dev/docs/components/Table.md)

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/components/VirtualList · Index for agents: https://tarve.dev/llms.txt
