Selection model
Understand the three selection channels, how a selection follows its records when the view changes, and which props turn a channel off.
Each grid keeps one selection. The selection has three channels, and each channel records its own kind of choice. The channels use view indexes. When the view rebuilds, they stay on the same records.
Selection channels
- The cell channel holds the anchor cell and a rectangular range around it. The anchor starts at the active cell and always lies inside the range. Alt+Arrow moves the active cell and keeps the anchor and the range, so the active cell can sit outside the range. With multi-range on, the channel also holds a stack of extra ranges from Ctrl or Cmd clicks. The stack never holds the main range.
- The row channel holds whole rows. A marker checkbox, a marker press and drag, and the row keys set it. The grid calls these rows the checked rows.
- The column channel holds whole columns. A header click and a header drag set it.
A plain header click clears the cell range and the row channel, then selects the column. With checkedRowsLifetime set to "until-cleared" or "across-filters", it keeps the row channel. A plain marker press clears the cell range and the column channel, then selects the row. A Ctrl, Cmd, or Shift click on a header keeps the row channel. The same click on a marker keeps the column channel. With headerClickBehavior="sort", a header click sorts the column and selects nothing. The overlay layer paints the column and row channels as full bands.
A view index is a position in the current sorted and filtered order. A selection holds view indexes. When the view changes, the grid translates them to row ids and column ids.
useDataGridSelection() reads the selection as a GridSelection. The row and column channels are CompactSelectionLike sets, and the exported CompactSelection class implements them.
runs() returns the members as sorted [start, end) runs. It costs less than toArray() for a large selection, such as 100,000 checked rows. This sample counts the runs of checked rows:
import { useDataGridSelection } from "@/components/data-grid/data-grid";
export function CheckedRunCount() {
const selection = useDataGridSelection();
return <span>{selection.rows.runs().length} runs of checked rows</span>;
}Selection follows records
A sort, a filter, a new data array, and a column move, hide, or pin all rebuild the view. The grid then carries the selection over by identity:
- The row channel follows the row ids of the checked rows. A checked row that leaves the view leaves the channel. When two rows share one row id, the check follows the first row with that id.
- The column channel follows column ids. A column that leaves the view leaves the channel.
- The active cell follows its record and its column.
- When the record or the column of the active cell leaves the view, the active cell keeps its view position, clamped into the view.
- A page change of a paged grid clears the active cell and drops the checks and the range of the rows that left the page.
checkedRowsLifetime="across-filters"keeps the checks by row id. A column selection stays. - When the rebuild puts other records or other columns under the range, the grid collapses the range onto the active cell. A clamp that moves the active cell collapses the selection onto it. A clamp that leaves the cell in place drops the range.
A row operation therefore never reaches a record that nobody selected. Delete rows after a sort deletes the same records you selected before the sort.
A checked row that a filter hides leaves the row channel. The grid remembers it by row id when checkedRowsLifetime is "across-filters". With a server sort or filter, also set totalRowCount. Checked rows explains both.
The channels behave the same in every data mode. On a server result, checkedRowsLifetime="across-filters" with totalRowCount keeps the checks by row id across pages, sorts, and filters. Select server rows covers that case.
Rows that an operation acts on
One function gives the selected rows to the delete rows shortcut, the duplicate row shortcut, and the row items of the cell menu. The export scope "selection" uses it too. It returns the union of the main range, the stacked ranges, and the checked rows. With "until-cleared" or "across-filters", any checked row makes the checked rows the whole result, and the ranges count for nothing.
When you select no row, the delete rows and duplicate row shortcuts act on the row of the active cell.
Your code reads the selected rows through details.getRowIds() on the second argument of onSelectionChange. It returns every selected row id in view order. useDataGridSelectedRows() returns the checked rows as a value for a bulk action.
Configurability
Four props of DataGridProvider turn parts of the selection off. All default to true. The type SelectionConfig describes them:
enableRowSelectionturns the row channel on or off.enableColumnSelectionturns the column channel on or off.enableRangeSelectionallows a range of more than one cell. When it isfalse, a drag or a Shift extension leaves a single active cell. Mod+A selects nothing. A Shift click on a marker or a header selects one row or one column.enableMultiRangeallows the stack. When it isfalse, a Ctrl or Cmd click acts as a plain click.
A disabled channel ignores its gestures and actions. With enableColumnSelection={false}, a header click does nothing. A controlled selection and setSelection still write the channel.
Related
Plugin overlays
Learn how a plugin paints into the overlay layer and the row bands, which context values it receives, and which coordinates it uses.
Cell type model
Understand how one cell type object drives display, editing, clipboard, sort, search, and filter, and which rules keep a custom type safe.