

<Preview name="VirtualizedDataTableExample" />

## Overview [#overview]

Virtualisation keeps large tables usable by rendering only the visible rows plus an overscan buffer. `DataTable` supports three layouts:

| Mode                     | When To Use                                             | Key Props                                                      |
| ------------------------ | ------------------------------------------------------- | -------------------------------------------------------------- |
| Container virtualisation | The table scrolls inside its own fixed-height container | `enableRowVirtualization`, `virtualMaxHeight`                  |
| Window virtualisation    | The page itself is the scroll container                 | `enableRowVirtualization`, `useBodyScroll`                     |
| Custom scroll container  | Another element owns scrolling                          | `enableRowVirtualization`, `useBodyScroll`, `getScrollElement` |

## Container Virtualisation [#container-virtualisation]

Container virtualisation is the default mode once `enableRowVirtualization` is on.

```tsx
<DataTable
  columns={columns}
  data={rows}
  enableRowVirtualization
  virtualMaxHeight={500}
  virtualRowHeight={40}
  virtualOverscan={8}
/>
```

## Window and Custom Scroll Virtualisation [#window-and-custom-scroll-virtualisation]

Use `useBodyScroll` when the scroll position should come from the page or from another scroll container.

```tsx
<DataTable
  columns={columns}
  data={rows}
  enableRowVirtualization
  useBodyScroll
  getScrollElement={() => scrollContainerRef.current}
  virtualRowHeight={40}
  virtualOverscan={50}
/>
```

## Row Measurement [#row-measurement]

`DataTable` estimates row height from `virtualRowHeight` and measures row elements dynamically during virtualisation. Give `virtualRowHeight` a realistic estimate to reduce layout correction.

Provide `measureElement` only when you need custom measurement behavior.

## API Reference [#api-reference]

| Prop                      | Type                                                                        | Default | Description                                                 |
| ------------------------- | --------------------------------------------------------------------------- | ------- | ----------------------------------------------------------- |
| `enableRowVirtualization` | `boolean`                                                                   | `false` | Enable row virtualisation                                   |
| `virtualRowHeight`        | `number`                                                                    | `40`    | Estimated row height in pixels                              |
| `virtualOverscan`         | `number`                                                                    | `20`    | Extra rows rendered above and below the viewport            |
| `virtualMaxHeight`        | `number \| string`                                                          | `600`   | Max container height in container virtualisation mode       |
| `useBodyScroll`           | `boolean`                                                                   | `false` | Use the page or another element as the scroll container     |
| `getScrollElement`        | `() => HTMLElement \| null`                                                 | -       | Custom scroll element getter for body-scroll virtualisation |
| `measureElement`          | `(element: Element, entry?: ResizeObserverEntry, instance?: any) => number` | -       | Custom row measurement logic                                |
| `debug`                   | `boolean`                                                                   | `false` | Log virtualisation diagnostics to the console               |