## Overview [#overview]

DataGrid automatically virtualizes large final row models and keeps smaller
tables in normal document flow. The decision uses the visible rows and columns
after filtering, grouping, expansion, and pivoting, so the same table can move
between native and virtual geometry as its view changes.

Leave `rowVirtualization="auto"` for normal use. Use `"always"` for a known
large surface or performance test, and `"never"` for a known-small table that
requires native row geometry. Vertical
[Cell Spanning](/components/data-grid/cell-spanning) also requires `"never"`.

Rows can have different heights and are measured after mounting.
`estimatedRowHeight` supplies the initial estimate. Adjust overscan only after
measuring visible blanking or unnecessary mounted work. Top- and bottom-pinned
rows remain mounted outside the virtual centre region.

## Example [#example]

The toolbar is ordinary viewport content rather than a virtual row. Scroll it
away to keep the table header at the top. Search to reduce the row model below
the automatic threshold; clear the search to return to virtual geometry.

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="DataGridRowVirtualizationScenario" />
  </Tab>

  <Tab value="Code">
    ```tsx
    <DataGrid table={table}>
      <DataGrid.Viewport
        aria-label="Matters"
        className="max-h-96"
        rowVirtualization="auto"
      >
        <MattersToolbar />
      </DataGrid.Viewport>
    </DataGrid>
    ```
  </Tab>
</Tabs>

## Diagnostics [#diagnostics]

Use `onDiagnosticsChange` on performance and test surfaces that need the
configured and resolved geometry, render-work estimate, and input-versus-mounted
dimensions. No diagnostic snapshots are created when the callback is omitted.
Expanded detail content is not included in mounted row or cell counts.

```tsx
<DataGrid.Viewport
  aria-label="Matters"
  onDiagnosticsChange={diagnosticsStore.publish}
/>
```

## API Reference [#api-reference]

### DataGrid.Viewport [#datagridviewport]

| Prop                      | Type                                         | Default  | Description                                                         |
| ------------------------- | -------------------------------------------- | -------- | ------------------------------------------------------------------- |
| `rowVirtualization`       | `"auto" \| "always" \| "never"`              | `"auto"` | Selects adaptive, forced virtual, or forced native row geometry.    |
| `virtualizationThreshold` | `number`                                     | `180000` | Render-work threshold used by automatic virtualization.             |
| `virtualizationOverscan`  | `number`                                     | `5`      | Rows mounted beyond each visible edge.                              |
| `estimatedRowHeight`      | `number`                                     | `48`     | Initial pixel estimate used until each mounted row is measured.     |
| `onDiagnosticsChange`     | `(diagnostics: DataGridDiagnostics) => void` | -        | Reports geometry, render work, and input-versus-mounted dimensions. |

Virtualization limits mounted DOM nodes without changing the final row model.
Table APIs and accessibility row counts continue to describe all rendered-model
rows.

### DataGridDiagnostics [#datagriddiagnostics]

| Field                          | Type                                        | Description                                           |
| ------------------------------ | ------------------------------------------- | ----------------------------------------------------- |
| `geometry.configured`          | `"auto" \| "always" \| "never"`             | Requested row-virtualization mode.                    |
| `geometry.resolved`            | `"native" \| "virtual"`                     | Geometry currently used by the viewport.              |
| `geometry.reason`              | `DataGridDiagnostics["geometry"]["reason"]` | Reason for the resolved geometry.                     |
| `geometry.estimatedRenderWork` | `number`                                    | Estimated work used by automatic mode.                |
| `geometry.renderWorkThreshold` | `number`                                    | Threshold compared with the estimate.                 |
| `inputs`                       | `DataGridDiagnosticsDimensions`             | Rows, columns, and body cells before virtualization.  |
| `mounted`                      | `DataGridDiagnosticsDimensions`             | Data rows, columns, and body cells currently mounted. |

### DataGridDiagnosticsDimensions [#datagriddiagnosticsdimensions]

| Field       | Type                                                             | Description                                                           |
| ----------- | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
| `bodyCells` | `number`                                                         | Data-body cells in the snapshot. Expanded-detail content is excluded. |
| `columns`   | `{ start: number, center: number, end: number, total: number }`  | Visible column counts by pinning region and in total.                 |
| `rows`      | `{ top: number, center: number, bottom: number, total: number }` | Data-row counts by pinning region and in total.                       |