DataGrid

DataGrid is a compound component for keyboard-aware grid navigation across rows and cells.

Root API

DataGrid is the root active-cell and keyboard-navigation container.

Prop	Type	Default
`ref`	`Ref<HTMLDivElement>`	—
Ref to the grid’s root element.
`apiRef`	`Ref<DataGridApiRef<K>>`	—
Ref to the grid’s imperative API. Exposes low-level structures for advanced scenarios: `grid` — matrix navigation helper; `keyMap` — Map`<K, [row, col]>` for fast lookups
`wrap`	`DataGridWrap`	—
Navigation wrap mode. 'horizontal' — wrap across columns within the same row; 'vertical' — wrap across rows within the same column; 'both' — enable both behaviors; undefined — no wrapping
`defaultActive`	`K`	`''`
Uncontrolled initial active (focused) cell key.
`active`	`K`	—
Controlled active (focused) cell key.
`onChangeActive`	`(active: K) => void`	—
Fires when the active (focused) cell key changes.
`exclude`	`DataGridExclude<K>`	—
Exclude cells from focus traversal. Can be: a single key; an array of keys; a predicate `(key) => boolean`
`rowDelta`	`number`	—
Page navigation row step for PageUp/PageDown. `undefined` — jump to the first/last row; `number` — move by N rows relative to the current row
`onArrow`	`(e: KeyboardEvent<HTMLDivElement>, node: MatrixNode<HTMLElement, K>, prevNode: MatrixNode<HTMLElement, K>) => void`	—
Fires on each Arrow navigation step after focus changes

Also accepts all <div> attributes.

Groups rows for navigation registration.

Prop	Type	Default
`scope`	`DataGridScope`	—
Optional logical group for grid cells. Allows the DataGrid to treat cells as part of the same page or section.

Also accepts all <div> attributes.

Row registration unit.

Prop	Type	Default
`row`required	`number`	—
Zero-based row index for all descendant cells. Provided to descendants via context.

Also accepts all <div> attributes.

Cell registration unit.

Prop	Type	Default
`col`required	`number`	—
Column index of the cell (0-based). Used together with row index from the row context to form grid coordinates: `[row, col]`.
`ref`	`Ref<HTMLDivElement>`	—
External ref to the cell root element. Will be merged with the internal `itemRef([row, col], key)` registration when the cell is not excluded.
`cellKey`	`DataGridCellKey`	—
Stable key that identifies the cell in the DataGrid matrix. If omitted, a key is derived as `${row}:${col}` from row/col.
`asChild`	`boolean`	`false`
When `true`, renders children via `Slot` and forwards props/refs to the child element instead of using a native `<div>`.
`excluded`	`boolean`	—
Exclude cells from focus traversal. Overrides value from root DataGrid

Also accepts all <div> attributes.

Advanced hook for root-level grid coordination.

Advanced hook for row-level custom abstractions.

Type	Definition	Notes
`DataGridCellKey`	cell key contract	Usually row and column based.
`DataGridCoordinates`	row/col coordinate shape	Used by navigation logic.
`DataGridWrap`	wrap mode union	Horizontal, vertical, or both.
`DataGridExclude`	exclusion contract	Sparse-grid navigation control.
`DataGridApiRef`	API ref contract	Advanced integrations.
`DataGridScope`	scope identifier	Separates logical grid groups when needed.

Active cell can be controlled or uncontrolled.
Navigation depends on row and cell registration order.
Exclusion and wrap mode affect the keyboard model directly.
The root is foundational; selection and picker semantics are layered on by derived components.

Prefer Table for static data display.
Use exclusion rules when the visible matrix is sparse.
Use rowDelta when PageUp/PageDown should move by a fixed amount instead of jumping to edges.
Retest interactive content inside cells carefully.