# DataGrid

> A virtualized grid with sorting, filtering and selection.

Virtualized controlled data grid with local/manual sort, filtering and row selection.

- Category: [Data display](https://tarve.dev/docs.md#data)
- Import: `import { DataGrid } from "@tarve/core";`
- Props type: `DataGridProps<T>` (generic)
- Source: [packages/core/src/desktop-controls.ts:213](https://github.com/omarcosr/tarve/blob/main/packages/core/src/desktop-controls.ts#L213)

## Usage

```tsx title="DataGrid.tsx"
import { DataGrid, type DataGridKey, type DataGridSort } from "@tarve/core";

const files = Array.from({ length: 5_000 }, (_, index) => ({ id: index, name: `file-${index}.ts`, size: index * 13 }));
let offset = 0;
let sort: DataGridSort | undefined = { column: "name", direction: "asc" };
let selected: DataGridKey[] = [];

<DataGrid
  id="files"
  rows={files}
  rowKey={(row) => row.id}
  height={400}
  offset={offset}
  selectionMode="multiple"
  selectedKeys={selected}
  sort={sort}
  columns={[
    { key: "name", header: "Name", value: (row) => row.name, sortable: true, searchable: true },
    { key: "size", header: "Size", value: (row) => row.size, sortable: true, align: "end" },
  ]}
  onScroll={(next) => {
    offset = next;
  }}
  onSortChange={(next) => {
    sort = next;
  }}
  onSelectionChange={(keys) => {
    selected = keys;
  }}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` (required) | `readonly DataGridColumn<T>[]` | — |  |
| `rowKey` (required) | `(row: T, index: number) => DataGridKey` | — |  |
| `rows` (required) | `readonly T[]` | — |  |
| `empty` | `Child` | `"No results."` |  |
| `filter` | `string` | `""` |  |
| `filterMode` | `"local" \| "manual"` | `"local"` |  |
| `height` | `number` | `360` |  |
| `offset` | `number` | `0` |  |
| `onRowActivate` | `(row: T, index: number) => void` | — |  |
| `onScroll` | `(offset: number, max: number, info: ScrollInfo) => void` | `() => {}` |  |
| `onSelectionChange` | `(keys: DataGridKey[]) => void` | — |  |
| `onSortChange` | `(sort: DataGridSort \| undefined) => void` | — |  |
| `overscan` | `number` | `3` |  |
| `rowHeight` | `number` | `40` |  |
| `selectedKeys` | `readonly DataGridKey[]` | `[]` |  |
| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` |  |
| `sort` | `DataGridSort` | — |  |
| `sortMode` | `"local" \| "manual"` | `"local"` |  |

## 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="DataGridColumn"
interface DataGridColumn<T> {
  key: string;
  header: Child;
  value?: (row: T, index: number) => unknown;
  render?: (row: T, index: number) => Child;
  width?: Style["width"];
  align?: Style["align"];
  sortable?: boolean;
  searchable?: boolean;
  compare?: (a: T, b: T) => number;
}
```

```ts title="DataGridKey"
type DataGridKey = string | number;
```

```ts title="DataGridSort"
interface DataGridSort {
  column: string;
  direction: DataGridSortDirection;
}
```

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

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

---

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