Selection and cell events
Read or control the selection, follow the active cell, and react to a click, a double-click, or a right-click on a cell.
onSelectionChange pairs with the selection prop. onActiveCellChange follows the active cell. Three more callbacks report a mouse event on a cell.
| Prop | Purpose | Default |
|---|---|---|
selection | The selection, controlled by your code | none |
defaultSelection | The selection, seeded once | none |
onSelectionChange | A committed selection change alters the selection | none |
onActiveCellChange | The active cell becomes a different cell, or clears | none |
onCellClick | A click lands on a cell | none |
onCellDoubleClick | A double-click lands on a cell | none |
onCellContextMenu | A right-click lands on a cell | none |
onSelectionChange
The callback receives the selection as a SelectionState and a details object of type SelectionChangeDetails. Every reference is a CellRef, a row id plus a column id. A sort, a filter, or a reorder does not change a CellRef.
| Field | Meaning |
|---|---|
anchor | The anchor of the primary range, or null |
range | The primary range as { start, end }, in either diagonal order, or null |
rangeStack | Earlier Ctrl or Cmd click ranges, oldest first |
rowIds | The row ids of the row channel, in view order |
columnIds | The column ids of the column channel, in view order |
The callback fires for a click, a range extend step, a row, column, or all selection, and a clear. If the selection equals the last known value, it does not fire. A sort that moves no selected row fires nothing. A value you pass in through selection does not fire it.
In scroll mode, rowIds holds the placeholder id __lazy-unloaded-<index> for an unloaded row. Test an id with isPlaceholderRowId(id) from data-grid, not with the prefix.
A pointer drag fires details.phase: "drag" for each step and one call with "end" on release. Check details.phase === "end" to act once per selection. A click, a key, a tap, and an API call report "end".
The active cell is not part of SelectionState. Use onActiveCellChange for it.
The callback runs after the grid writes the selection. If it throws, the grid prints [data-grid] onSelectionChange threw: as a console error, and its other updates still run. onActiveCellChange follows the same rule. See Callback timing and errors.
Control the selection
Pass selection to control the state. A gesture writes to the grid and fires the callback at once. A new value replaces the selection without firing the callback. It must differ from the current selection and from the last fired value.
A value with an anchor moves the active cell to it. defaultSelection seeds the selection once. If you pass both, selection wins and development mode warns once. This sample controls the selection:
import { useState } from "react";
import {
DataGrid,
defineColumns,
EMPTY_SELECTION_STATE,
type SelectionState,
} from "@/components/data-grid/data-grid";
type Row = { id: string; name: string };
const columns = defineColumns<Row>()([
{ id: "name", header: "Name", accessorKey: "name" },
]);
function Grid({ rows }: { rows: Row[] }) {
const [selection, setSelection] = useState<SelectionState>(
EMPTY_SELECTION_STATE,
);
return (
<DataGrid
defaultData={rows}
columns={columns}
selection={selection}
onSelectionChange={(next) => setSelection(next)}
/>
);
}The grid resolves each reference against its current view. It drops a range with an unresolved corner and every unresolved id in rowIds and columnIds. An anchor outside its range resets to range.start. Development mode warns once per grid.
Read the values
The second argument holds phase and two functions. The functions are lazy, so a handler that ignores them pays nothing on each drag step.
getValues()returns the raw cell values of the primary range asunknown[][], one array per view row. It returns[]without a range. It readsrangeonly and skipsrangeStack. In scroll mode, it returnsundefinedfor an unloaded cell.getRowIds()returns the ids of every selected row in view order. It covers the checked rows and every row underrangeandrangeStack. It skips unloaded rows, whole-column selections, and checked rows that left the view. Pass the ids todeleteRows.useDataGridSelectedRowsalso reports the hidden checked rows.
Outside the callback, useDataGridGetSelectionValues() returns a stable function that behaves like getValues.
Clear the selection
An empty selection has range: null and both channels empty. From non-empty to empty, the callback fires once.
onActiveCellChange
The payload is a ViewCellRef or null. The callback fires when:
- the active cell becomes a different cell,
- a sort, a filter, a data change, or a column hide, reorder, or pin moves the active cell to another view position,
- another record comes under the active cell, such as a lazy row that loads,
- the grid clears the active cell.
Re-selecting the same cell does not fire it. A rebuild that keeps the record and column in place does not fire it. A value-only write to the cell does not fire it.
When the row or column of the active cell leaves the view, the grid moves the active cell to the nearest cell in the view. The selection collapses onto that cell. If the active cell is the edited cell, the edit cancels and the active cell becomes null. When the view becomes empty, the active cell is null and the current range clears.
When a text field outside the grid holds focus, an active cell move does not take focus. Call focus() on the grid handle to move focus into the grid.
Mouse events on a cell
onCellClick, onCellDoubleClick, and onCellContextMenu receive a CellClickCtx and the native MouseEvent. The context holds value, row, column, rowId, columnId, viewRowIndex, and viewColumnIndex.
These callbacks only report. They do not stop what the gesture does. Their types are OnCellClick, OnCellDoubleClick, and OnCellContextMenu. They skip pinned rows and loading placeholders. A double-click or right-click inside an open editor fires neither callback.
onCellClick
The callback fires once per click, modifier clicks included, beside the selection change. A double-click fires it twice, then onCellDoubleClick.
onCellDoubleClick
The callback fires on a double-click, also on a readOnly grid. On an editable cell the edit still starts, and only onBeforeEditStart can stop it.
onCellContextMenu
The callback fires on a right-click. The context menu add-on is not affected.