Pointer selection
Select cell ranges, rows, and columns with a mouse, a pen, or a finger, and choose what a header click does.
Users select cells, rows, and columns with the pointer. A press and drag paints a rectangular range. A marker press checks a row. A header press selects a column. Four enable* props switch these channels off, and headerClickBehavior decides what a header click does.
Mouse gestures
A mouse or a pen uses these gestures:
- Press a cell and drag. The grid paints a rectangular range from the pressed cell to the pointer, in any direction. It scrolls while the pointer sits near an edge.
- Shift+click extends the range from the anchor cell to the clicked cell.
- Ctrl/Cmd+click adds a new range to the stack.
- Press a column header and drag to select adjacent columns. Shift+click extends from the last selected column. Ctrl/Cmd+click adds a column.
- Press a row marker and drag to check rows. Drag back over checked rows to shrink the span.
The marker gestures are in Checked rows.
The grid root turns off native text selection.
The reorder marker modes move a row only from the drag handle, and that drag leaves the selection as it was. A drag from the number or the checkbox still selects.
Touch gestures
A touch screen scrolls natively. The grid reads the input type of each press. A laptop with a touch screen and a trackpad gets touch gestures from the screen and mouse gestures from the trackpad.
Use a touch device or browser device mode. Drag a handle to select several cells, then press and hold to open the context menu. Fill down and Fill right appear for a touch selection.
| Gesture | Result |
|---|---|
| Tap a cell | Selects the cell. A scroll or a pan selects nothing. |
| Tap the checkbox of a checkbox cell | Toggles the value. A tap elsewhere in the cell selects it. A read-only grid does not toggle. |
| Double-tap a cell | Starts editing, or toggles a checkbox cell. Two taps on the same cell within 300 ms and 10 px make a double-tap. A read-only grid does not edit. |
| Tap a column header | Selects the column. With headerClickBehavior="sort", it sorts the column. |
| Tap the number of a row marker | Checks only this row. |
| Tap the checkbox of a row marker | Toggles this row and keeps the other checks. |
| Long-press (500 ms) a cell or a header | Fires a contextmenu event, with every headerClickBehavior. The context menu add-on opens its menu. The click after a long press does nothing. |
| Drag a selection handle | Extends the range from the opposite corner. The grid scrolls at the edges. |
After a touch selection, two selection handles appear at the top-start and bottom-end corners of the range. A key press other than a modifier hides them, and so does an open editor. A press that moves more than 10 px counts as a pan, not a tap.
The grid root sets touch-action: manipulation. A double-tap does not zoom the page, and pinch zoom stays available. For targets that are easier to hit, use density="comfortable".
Header click behavior
headerClickBehavior picks what a plain header click does:
| Value | A plain header click |
|---|---|
"select" | Selects the whole column. A press and drag selects adjacent columns. |
"sort" | Cycles the column through ascending order, descending order, and no sort. Shift+click adds the column to a multi-sort. |
"none" | Does nothing. |
Only "select" mode selects columns. In "sort" and "none" mode, a header press selects no column. When a sort list or your own UI drives the sort, set "none". A column with sortable: false never sorts on click, and useDataGridActions().setSorts() still sorts it. Sorting covers the sort itself.
The following example sorts on a header click:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Person = { id: string; name: string; age: number };
const columns = defineColumns<Person>()([
{ id: "name", header: "Name", accessorKey: "name", type: "text" },
{ id: "age", header: "Age", accessorKey: "age", type: "number" },
] as const);
export function People({ rows }: { rows: Person[] }) {
return (
<DataGrid
data={rows}
columns={columns}
headerClickBehavior="sort"
/>
);
}Pointer props
| Prop | Type | Default |
|---|---|---|
enableRangeSelection | boolean | true |
enableMultiRange | boolean | true |
enableColumnSelection | boolean | true |
enableRowSelection | boolean | true |
headerClickBehavior | "select" | "sort" | "none" | "sort" with totalRowCount, else "select". |
enableRangeSelection={false}limits a cell drag and Shift+click to the active cell.enableMultiRange={false}turns Ctrl/Cmd+click into a plain click.enableColumnSelection={false}makes a header press select no column. In"sort"mode, a header click still sorts.enableRowSelection={false}makes a marker press do nothing.
Related
- Checked rows: marker gestures and row ranges
- Keyboard navigation: the same selection from the keyboard
- Selection model: the channels behind these gestures
- Sorting: what
"sort"mode runs - DataGrid props: every prop of the grid
Undo for code changes
Make changes that your code applies undoable with record or a change source, pick which sources the history keeps, and reset it when you swap the data.
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.