DataGridSelectable

DataGridSelectable extends DataGrid with active-cell management and single, multiple, or range selection.

Root API

Prop	Type	Default
`selection`	`S`	`'single'`
Selection mode. `'single'` — only one cell can be selected at a time; `'multiple'` — independent multi-selection (toggle per cell); `'range'` — range selection between two points (Shift + arrows or pointer drag)
`disabled`	`DataGridDisabled<K>`	—
Predicate or map of disabled cells. Can be: a function `(key) => boolean`; an array of disabled keys; a single key. Disabled cells cannot be selected or focused.
`excludeDisabled`	`boolean`	`true`
—
`expandable`	`boolean`	`true`
Enables expanding selection ranges (Shift + Arrow or mouse drag).
`defaultActive`	`K`	—
Uncontrolled initial active cell.
`active`	`K`	—
Controlled active cell.
`selected`	`S extends "single" ? K \| null : K[]`	—
Controlled selected cells. In `'single'` mode `null` means controlled with nothing selected.
`defaultSelected`	`S extends "single" ? K : K[]`	—
Uncontrolled initially selected cells.
`from`	`K`	—
Range boundaries. If provided, limits selection to cells between `from` and `to` based on the `compare` function.
`to`	`K`	—
—
`resolveRange`	`(start: DataGridResolveValue<K>, end: DataGridResolveValue<K>, grid: Grid<HTMLElement, K>) => K[]`	—
Custom range resolution logic for `selection="range"`. Given start and end values, returns the list of keys forming the range.
`equals`	`(start: K \| undefined, end: K \| undefined) => boolean`	—
Custom equality comparator for comparing two cell keys. Defaults to strict equality (`===`).
`compare`	`(a: K, b: K) => -1 \| 0 \| 1`	—
Custom ordering comparator for comparing two cell keys. Should return `-1`, `0`, or `1`.
`onSelectCell`	`(value: S extends 'single' ? K : K[]) => void`	—
Fires when the user selects cell. Receives the list of selected cell keys.
`onChangeActive`	`(active: K) => void`	—
Fires when the active (focused) cell changes.
`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
`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.

Child Parts API

`DataGridSelectableRowGroup`

Groups rows and can provide scope separation for advanced compositions.

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.

`DataGridSelectableRow`

Represents one row of cells in the matrix.

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

Also accepts all <div> attributes.

`DataGridSelectableCell`

Represents one selectable cell.

Prop	Type	Default
`disabled`	`boolean`	—
Disables click and keyboard selection. Overrides value from root DataGrid
`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.

the cell key model should stay stable across renders

Hooks

`useDataGridSelectableContext`

Advanced hook for reading selection and disabled state in custom cell wrappers.

Types

Type	Definition	Notes
`DataGridSelectableProps<K, S>`	root prop type	Extends `DataGridProps<K>`.
`DataGridSelectableRowGroupProps`	row-group props	Grouping and scope behavior.
`DataGridSelectableRowProps`	row props	Row coordinate metadata.
`DataGridSelectableCellProps`	cell props	Cell coordinate and render props.
`DataGridSelection`	`'single' \| 'multiple' \| 'range'`	Selection mode.
`DataGridDisabled<K>`	disabled map type	Predicate, list, or key.

State Model

Active state and selected state can both be controlled or uncontrolled.
Range mode uses expansion logic driven by keyboard and pointer movement.
Disabled and excluded cells change both selection and navigation behavior.

Integration Notes

Keep key ordering stable when using compare and range logic.
Use DataGridPicker when the visual picker layer should be standardized.
Test pointer drag, shift-key expansion, and wrapped navigation together in real flows.