Data Grid
A spreadsheet-like grid: move between cells with the arrow keys and edit values in place, with validation.Editable, with validation
Preview
Code
Double-click a cell, or press Enter, to edit.
Installation
Package
CLI (copy source)
pnpm
pnpm add @advui/datanpm
npm install @advui/dataUsage
import { DataGrid, type DataGridColumn } from '@advui/data'
const columns: DataGridColumn<Row>[] = [
{ id: 'township', header: 'Township' },
{ id: 'reached', header: 'Reached', type: 'number', editable: true },
]
<DataGrid aria-label="Reach by township" data={rows} onDataChange={setRows} columns={columns} />Examples
Read-only, with custom cells
Preview
Code
API reference
DataGrid
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label required | string | — | Names the grid. |
columns required | DataGridColumn<T>[] | — | Column definitions (below). |
data | T[] | — | The rows. Accepted edits come back as a new array. |
defaultData | T[] | — | Starting `data` when uncontrolled. |
onDataChange | (data: T[]) => void | — | Called with the new `data`. |
onCellChange | (change: DataGridCellChange<T>) => void | — | One accepted edit: `row`, `rowId`, `rowIndex`, `columnId`, `value`, `previousValue`. Save it here. |
getRowId | (row, index) => string | `row.id`, then the index | Stable id for React keys and `onCellChange`. |
getRowLabel | (row) => string | the first column | Names the row in cell names and errors ("Reached, Hakha"). |
readOnly | boolean | false | No editing. |
size | 'sm' | 'md' | 'md' | Row height. |
labels | Partial<DataGridLabels> | — | Edit hint and error text, for translation. |
DataGridColumn<T>
| Prop | Type | Default | Description |
|---|---|---|---|
id required | string | — | Key; the row field by default. |
header required | string | — | Header text. |
editable | boolean | false | Cells can be edited. |
type | 'text' | 'number' | 'text' | `number` right-aligns, shows the number keyboard and parses the input. |
validate | (value, row) => string | null | — | Return a message to reject an edit. The cell stays open with the error. |
accessor | (row: T) => string | number | null | undefined | — | Reads a value that is not a plain field. Default: `row[id]`. |
setValue | (row: T, value: string | number | null) => T | — | Writes an edited value that is not a plain field; returns the new row. |
format | (value, row) => string | — | Display text, e.g. thousands separators. |
cell | (row) => ReactNode | — | Custom display content. |
width | number | 160 | Pixels. The grid scrolls sideways when wider than its container. |
align | 'start' | 'center' | 'end' | — | Alignment. |
Accessibility
- Web follows the WAI-ARIA grid pattern: a named
gridwithrow,columnheaderandgridcellroles, row and column indexes, and one tab stop (the active cell). - The editor is a text field named by its column and row ("Reached, Hakha").
- A rejected edit keeps the field open, marks it
aria-invalid, and says why in a polite live region under the grid. - On iOS and Android each cell reads its column, row and value; editable cells are buttons with a "Double-tap to edit" hint.
| Key | Action |
|---|---|
| Arrow keys | Move between cells. |
| Home / End | First or last cell in the row (with Ctrl or ⌘: in the grid). |
| Page Up / Page Down | Move five rows. |
| Enter / F2 | Edit the cell. Typing a character starts editing with it. |
| Delete / Backspace | Edit the cell, starting empty. |
| Enter / Tab (editing) | Save and move down or right (Shift: up or left). |
| Escape (editing) | Cancel the edit. |
| Tab | Leave the grid. |
Responsive behavior
Columns have fixed widths; the grid scrolls sideways on narrow screens.
Platform notes
Web
Double-click a cell to edit it. Clicking elsewhere saves the edit, or drops it when it is invalid.
iOS
Tap an editable cell to edit; the keyboard’s Done key saves.
Android
Same as iOS.