Checked rows
Let users check rows with markers, row spans, or keys, keep the checks across cell clicks and filters, and run row operations on them.
A checked row is a row whose marker checkbox is on. Users check rows with the marker checkbox, the row number, the header checkbox, or keys. A sort or a new data array rebuilds the view, and checked rows follow their records. Row operations such as Delete rows act on them. For a server grid, see Select server rows.
Check a few rows, then open the Role filter and keep one role. The status bar counts the checked rows the filter hides. Clear the filter and the checks come back.
Show the checkboxes
The row checkboxes and the select-all checkbox in the header need rowMarkers="checkbox". The default rowMarkers is "none", which renders no marker column. The other checkbox modes are on Row markers:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Person = { id: string; name: string };
const cols = defineColumns<Person>()([
{ id: "name", header: "Name", accessorKey: "name" },
]);
export function People({ rows }: { rows: Person[] }) {
return <DataGrid defaultData={rows} columns={cols} rowMarkers="checkbox" />;
}A click on the header checkbox checks every row of the view, which is the shown page on a paged grid. On a server grid with unloaded rows, it selects all matching (Select server rows). A second click unchecks them all.
Check a span of rows
The row that you checked or unchecked last is the anchor. A Shift step checks the rows from the anchor to the target row. Each Shift step replaces the previous one, so the span grows and shrinks. Rows outside the span keep their state.
| Gesture | Result |
|---|---|
| Click a checkbox | Toggles the row. The row becomes the anchor. |
| Click a number | Checks only this row and unchecks the others. If this row is the only checked row, it unchecks it. |
| Ctrl/Cmd+click a number or a checkbox | Toggles the row and keeps the other checked rows. |
| Shift+click | Checks the rows from the anchor to the clicked row. After an uncheck, the span unchecks its rows. |
| Ctrl/Cmd+Shift+click | Keeps the current span and adds the rows from the anchor to the clicked row. |
| Press a number or a checkbox and drag | Moves the end of the span with the pointer. A drag that starts on a checked checkbox unchecks the rows. |
| Shift+press and drag | Moves the end of the span from the anchor row. |
| Shift+click without an anchor | Starts at the active row. Without an active row, it checks only the clicked row. |
A sort or a filter ends the span. The next Shift+click then starts from the anchor row. The header checkbox and Esc clear the anchor. The next Shift+click then starts at the active row.
Click row 1, Shift+click row 5, and Shift+click row 3. The grid checks rows 1 to 3.
Check rows by keyboard
The marker checkboxes are not tab stops. These keys check rows instead:
- Ctrl+Shift+Space (
toggleRow) checks or unchecks the active row. The other checked rows stay checked. - Mod+Shift+Enter (
toggleAllRows) does what the header checkbox does. When every row is checked, it unchecks them all. - Shift+Space (
selectRow) checks only the active row. It follows the rules of a click on a number.
After selectRow or toggleRow, these keys move the end of the span and the active row:
- Shift+ArrowUp and Shift+ArrowDown (
extendUp,extendDown) check the rows from the anchor to the new end. Reverse to shrink the span. - Shift+Home, End, PageUp, and PageDown move the end to the first row, the last row, or one page away.
After a click on a cell, Shift+Arrow extends the cell range. Without a row check, Shift+Home and its siblings do nothing, and the browser keeps them.
To check separate rows, move with Alt+Arrow, which keeps the selection. Then press Ctrl+Shift+Space on each row.
A check or uncheck reads the checked-row count in the live region. Esc and Ctrl/Cmd+A also announce the new count. The count includes hidden checked rows, not the rows of a cell range. labels.grid.rowsChecked sets the text.
Choose how long checks last
checkedRowsLifetime sets how long the checked rows last:
| Value | The checked rows stay until |
|---|---|
'until-click' (default without totalRowCount and without a checkbox marker) | The user selects a cell or a column. |
'until-cleared' | Esc, Ctrl/Cmd+A, a click on a row number, a marker checkbox, the header checkbox, clearSelection(), or a row delete changes them. |
'across-filters' | Same as 'until-cleared'. A filter or a page change that hides a checked row keeps its check, and the grid checks the row again when it shows again. |
A click outside the grid, or in its empty space, clears the cell range and the column selection but never the checked rows.
Set 'until-cleared' to keep the checks across cell selections.
With 'until-cleared' and 'across-filters', row operations act on the checked rows when any row is checked. This covers Delete rows, Duplicate row, Move rows, and the row items of the cell context menu. Without a checked row, they act on the cell range, then on the active row. Copy and cut read the cell range when one exists, and the checked rows when it does not.
Read the checked rows
getSelection().rowIds on the grid API returns the ids of the checked rows that the view shows. getSelectedRows() returns what useDataGridSelectedRows() returns, the hidden checked rows included. onSelectionChange receives the same rowIds on each change. This sample reads the ids on a button click:
"use client";
import { useRef } from "react";
import {
DataGrid,
defineColumns,
type DataGridApi,
} from "@/components/data-grid/data-grid";
type Order = { id: string; customer: string };
const columns = defineColumns<Order>()([
{ id: "customer", header: "Customer", accessorKey: "customer" },
]);
export function Orders({ orders }: { orders: Order[] }) {
const gridRef = useRef<DataGridApi<Order> | null>(null);
const logChecked = () =>
console.log(gridRef.current?.getSelection().rowIds ?? []);
return (
<>
<button type="button" onClick={logChecked}>Log checked ids</button>
<DataGrid
ref={gridRef}
data={orders}
columns={columns}
rowMarkers="checkbox"
checkedRowsLifetime="until-cleared"
/>
</>
);
}onSelectionChange fires for each step of a drag with details.phase: "drag", then once with "end" on release. Check details.phase === "end" to act on settled selections only. See Selection and cell events.
To act on checks that a filter hides, read useDataGridSelectedRows() inside the grid. It returns { mode: "ids", ids, excludedIds: [], count } with the visible and the remembered ids. After select all matching, it returns { mode: "allMatching", excludedIds, count, spec }. The remembered ids need checkedRowsLifetime="across-filters". Select all matching needs that and totalRowCount. This component sits inside DataGridProvider and shows the count:
import { useDataGridSelectedRows } from "@/components/data-grid/data-grid";
export function CheckedCount() {
const selected = useDataGridSelectedRows();
return <span>{selected.count ?? "all"} checked</span>;
}Run bulk actions builds a bar with update, delete, and export buttons on these ids.
Hidden checked rows
A filter or a page change removes the checked rows it hides. Set checkedRowsLifetime="across-filters" to remember them. The grid checks a remembered row again when it shows again. A sort keeps both the visible and the hidden checks.
Hidden checked rows stay out of the controlled selection and select all. Row operations, the export scope 'selection', and the clipboard read only the visible checked rows. When every checked row is hidden, Delete rows, Duplicate row, and Move rows do nothing, and the Duplicate and Delete menu items turn off.
Esc, Ctrl/Cmd+A, the header checkbox, clearSelection(), setSelection(null), and an empty controlled selection also remove the hidden checks. A click on a row number and a non-empty setSelection value keep them. Switching to sortMode="server" or filterMode="server" without totalRowCount clears them.
useDataGridHiddenCheckedCount() returns their number. DataGridStatusBar shows it as (+3 hidden) beside the selection stats. With fewer than two non-undefined cells selected, it shows 3 hidden checked rows.
The grid remembers at most 100,000 hidden checked rows. Without totalRowCount, a grid that sorts or filters on the server behaves like 'until-cleared', and so does a grid with unloaded rows. In development, the grid warns once about the cap and once about the fallback. useDataGridSelectionConfig() returns the lifetime that applies.
Server mode
A server grid defaults to checkedRowsLifetime="across-filters" when it sets totalRowCount. A checked row that leaves data stays checked by row id. Select server rows covers page changes, scroll mode, and select all matching.
Checked row props
| Prop | Type | Default |
|---|---|---|
enableRowSelection | boolean | true |
checkedRowsLifetime | CheckedRowsLifetime | 'across-filters' with totalRowCount, else 'until-cleared' with a checkbox marker, else 'until-click'. Without totalRowCount, a server-sorted or server-filtered grid treats 'across-filters' as 'until-cleared'. |
totalRowCount | number | null | none |
announceResults | boolean | false |
onBeforeDeleteRows | (ctx: { rowIds: readonly string[]; hiddenCount: number; signal: AbortSignal }) => boolean | Promise<boolean> | none |
announceResultsreads the row count of the view after a filter or sort change. See Screen reader support.onBeforeDeleteRowsruns before every row delete, except asource: "stream"delete. Afalseresult cancels the delete. See Row operations.
Related
- Keyboard navigation: the full keymap
- Row markers: the checkbox and number column
- Select server rows: checks across pages
- Selection model: how the channels relate
- DataGrid props: every prop of the grid