gridcn2.0.0
Selection and shortcuts

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.

Row markers
Name
Role
Score
Silent Tiger
Viewer
4
Quick Lion
Viewer
89
Swift Wolf
Manager
80
Eager Lion
User
51
Eager Tiger
Viewer
83
Silent Wolf
User
15
Swift Lion
Viewer
62
Eager Lion
Manager
42
Eager Eagle
Editor
35
Bold Tiger
Editor
52
Bold Bear
User
28
Swift Wolf
Manager
9
Swift Bear
Viewer
45
Eager Wolf
Editor
44
Swift Eagle
Viewer
51
Quick Lion
Manager
28
Bold Wolf
Editor
76
Swift Eagle
Admin
26
Eager Eagle
Manager
70
Eager Bear
Editor
67
Silent Lion
Manager
89
Silent Tiger
Manager
40
Eager Tiger
Manager
82
Silent Lion
Admin
16
Bold Eagle
Admin
38
Bold Lion
Viewer
3
Quick Tiger
Viewer
41
Bold Eagle
Editor
10
Swift Tiger
Editor
6
Silent Lion
Viewer
42

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.

GestureResult
Click a checkboxToggles the row. The row becomes the anchor.
Click a numberChecks 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 checkboxToggles the row and keeps the other checked rows.
Shift+clickChecks the rows from the anchor to the clicked row. After an uncheck, the span unchecks its rows.
Ctrl/Cmd+Shift+clickKeeps the current span and adds the rows from the anchor to the clicked row.
Press a number or a checkbox and dragMoves the end of the span with the pointer. A drag that starts on a checked checkbox unchecks the rows.
Shift+press and dragMoves the end of the span from the anchor row.
Shift+click without an anchorStarts 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:

ValueThe 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

PropTypeDefault
enableRowSelectionbooleantrue
checkedRowsLifetimeCheckedRowsLifetime'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'.
totalRowCountnumber | nullnone
announceResultsbooleanfalse
onBeforeDeleteRows(ctx: { rowIds: readonly string[]; hiddenCount: number; signal: AbortSignal }) => boolean | Promise<boolean>none
  • announceResults reads the row count of the view after a filter or sort change. See Screen reader support.
  • onBeforeDeleteRows runs before every row delete, except a source: "stream" delete. A false result cancels the delete. See Row operations.

On this page