Store hooks
Look up each hook that reads grid state or reaches the grid from code, with its return value and the page that uses it.
Store hooks read the state of one grid. Inside a DataGridProvider they work. Outside it, they throw. Two items differ: useDataGridStoreProps runs outside the provider and creates the store, and createDataGridSelector is a factory that you call once at module scope. Import them from @/components/data-grid/data-grid. A hook that reads state subscribes to its own slice, so a component re-renders only when that slice changes.
| Group | Hooks |
|---|---|
| Handle and actions | useDataGridActions, useDataGridApi, useDataGridStoreProps, useDataGridScrollToCell, useDataGridScrollToCellAt, useDataGridClipboard |
| Rows and addresses | useDataGridViewIndex, useDataGridViewStale, useDataGridRow, useDataGridRowId, useDataGridRowIds, useDataGridRowIdToViewRow |
| Cells and editing | useDataGridReadOnly, useDataGridActiveCell, useDataGridActiveColumn, useDataGridEditing, useDataGridCellEditingError, useDataGridCellState, useDataGridRowCellState, useDataGridCellTypes |
| Selection | useDataGridSelection, useDataGridGetSelectionValues, useDataGridSelectedRows, useDataGridHiddenCheckedCount |
| Columns | useDataGridVisibleColumns, useDataGridAllColumns, useDataGridIsColumnHidden, useDataGridColumnWidth, useDataGridColumnWidths |
| Sort, filter, and search | useDataGridSortState, useDataGridFilterState, useDataGridSearchText |
| Labels, keys, and saves | useDataGridLabels, useDataGridKeymap, useDataGridCellErrors, useDataGridRowSaveStatus, useDataGridPendingSaveCount, useDataGridGatePending |
| Typed selector | createDataGridSelector |
| Typed hooks | createDataGridHooks |
Handle and actions
Hooks that reach the grid from code.
| Hook | Returns | Meaning |
|---|---|---|
useDataGridActions | DataGridActions | The actions object. Its identity never changes, so the hook never re-renders. Actions A to Z lists each action. |
useDataGridApi | DataGridApi<TData> | The imperative handle. useDataGridApi(ref?) returns the handle. Pass a ref to also assign it to that ref. Its identity is stable for the grid's lifetime. |
useDataGridStoreProps | { store, actions } | Creates the store outside the provider. Feed store to DataGridProvider. |
useDataGridScrollToCell | (ref: CellRef) => void | Scrolls a cell into view. It does nothing before DataGridRoot mounts, and warns in development for a ref that does not resolve. |
useDataGridScrollToCellAt | (coord: ViewCoord) => void | The same scroll for a view coordinate. |
useDataGridClipboard | UseDataGridClipboardResult | Returns copy, cut, and pasteFromClipboard. copy and cut resolve "ok", "fallback", "failed", or "no-selection". cut also resolves "refused" while a cell editor is open. pasteFromClipboard resolves a PasteFromClipboardResult: "ok", "permission-denied", "empty" (the clipboard holds no text), or "refused" (the grid started no paste, as Clipboard lists). The hook takes an optional { sanitizeFormulas }. Its default is the sanitizeClipboardFormulas prop. |
These actions have no feature page:
setActiveCellAtsets the active cell at aViewCoord, or clears it withnull.extendToAtextends the selection to the cell at aViewCoord.extendSelectiongrows the selection by one cell in a direction ("up","down","left","right"), or to the edge with{ toEdge: true }. It does nothing whenenableRangeSelectionisfalse.pushRangeAtadds a range to the cell at aViewCoord, like a Ctrl/Cmd+click. WithoutenableMultiRange, it selects the cell like a click.checkRowRangechecks or unchecks the rows from the anchor row to a view row index. It does nothing whenenableRowSelectionisfalse.clearCellSelectionclears the cell range and the selected columns and keeps the checked rows.commitCellEditvalidates and commits the value of the open edit, then moves the active cell by an optional{ dx, dy }. A rejected value keeps the edit open and sets the editing error.commitCellValueAtvalidates and writes a value at aViewCoordwithout an edit session, like a checkbox click.deleteSelectionclears every writable cell of the selection to the empty value of its cell type, as one change.applyCellUpdateswrites a list of{ viewRowIndex, columnId, value }updates as one change with asource. It skips read-only cells and unchanged values. Withoutrejectedandwarnings, it runs the columnvalidatelike a paste. Pass them to report your own results instead.
Rows and addresses
Hooks that read rows. State and view index explains the addresses.
Cells and editing
Hooks that read the active cell and the edit session.
Show the active cell and the read-only flag in a status line:
import {
useDataGridActiveCell,
useDataGridReadOnly,
} from "@/components/data-grid/data-grid";
export function CellStatus() {
const cell = useDataGridActiveCell();
const readOnly = useDataGridReadOnly();
return (
<span>
{cell ? `Row ${cell.row + 1}, column ${cell.col + 1}` : "No active cell"}
{readOnly ? " (read only)" : ""}
</span>
);
}Selection
Hooks that read the selection. Selection model explains the channels.
| Hook | Returns | Meaning |
|---|---|---|
useDataGridSelection | GridSelection | The selection in view indexes. The selection prop, onSelectionChange, and getSelection() use ids (SelectionState), so they survive a sort or a filter. |
useDataGridGetSelectionValues | () => unknown[][] | A stable callback. Each call reads the values of the main range at call time, or [] without a range. |
useDataGridSelectedRows | DataGridSelectedRows | The checked rows as a value for a bulk action. Mode "ids" holds ids and count. Mode "allMatching" holds excludedIds, count (or null), and the spec to send. See Select server rows. |
useDataGridHiddenCheckedCount | number | The count of checked rows that left the view (a filter, a page change, or a window move) and checkedRowsLifetime="across-filters" remembers. It is 0 after selectAllMatching(). |
Columns
Hooks that read column state. Column visibility uses them.
Sort, filter, and search
Hooks that read the spec. Server rows contract sends it to a backend.
| Hook | Returns | Meaning |
|---|---|---|
useDataGridSortState | SortSpec[] | The active sorts. |
useDataGridFilterState | FilterNode[] | The active filter tree. |
useDataGridSearchText | string | The quick-search text. |
Labels, keys, and saves
Hooks for text, keys, and server results.
| Hook | Returns | Meaning |
|---|---|---|
useDataGridLabels | DataGridLabels | The labels: the defaults merged with your labels prop. useOptionalDataGridLabels from @/components/data-grid/data-grid-sdk returns the same labels, or null outside a provider. |
useDataGridKeymap | Keymap | The effective keymap: defaults, plugin keymaps, then your keymap prop. It leaves out a binding that never matches: an unknown modifier, an unknown key name, or an empty key. An action with no live binding reads []. |
useDataGridCellErrors | ReadonlyMap<string, string> | The map of cell errors, keyed "rowId:columnId". The server sets them with setCellErrors, and a column with validationMode: "warn" sets them on a value it accepts with a warning. A cell renders its own error through useDataGridCellState. |
useDataGridRowSaveStatus | RowSaveStatus | undefined | "saving" while the onSave promise of the row is pending, "failed" after a refusal, else undefined. |
useDataGridPendingSaveCount | number | The count of onSave promises that have not settled. |
useDataGridGatePending | ReadonlySet<GateName> | The names of the gates whose promise has not settled. See Cancel async gates. |
createDataGridSelector
createDataGridSelector<TData>() returns a hook that reads any slice of the store. Create the hook once at module scope. The selector receives the store state with data typed as readonly TData[]. The hook takes (selector, eq?). eq defaults to Object.is and decides when the component re-renders.
Sum a column in a component below the provider:
import { useMemo } from "react";
import { createDataGridSelector } from "@/components/data-grid/data-grid";
type Order = { id: string; total: number };
const useOrderSelector = createDataGridSelector<Order>();
export function TotalBadge() {
const data = useOrderSelector((state) => state.data);
const total = useMemo(
() => data.reduce((sum, row) => sum + (row?.total ?? 0), 0),
[data],
);
return <span>{total}</span>;
}createDataGridHooks
createDataGridHooks<TData>() returns useDataGridApi, useDataGridRow, useDataGridVisibleColumns, useDataGridAllColumns, and useDataGridSelector, with the row type fixed. Call it once at module scope:
import { createDataGridHooks } from "@/components/data-grid/data-grid";
type Order = { id: string; total: number };
export const { useDataGridRow, useDataGridSelector } =
createDataGridHooks<Order>();
export function FirstTotal() {
const row = useDataGridRow(0);
const count = useDataGridSelector((state) => state.data.length);
return (
<span>
{row?.total} of {count} rows
</span>
);
}