gridcn2.0.0
Selection and shortcuts

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.

headerClickBehavior
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

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.

Name
Role
Age
Score
Silent Tiger
Viewer
63
4
Quick Lion
Viewer
67
89
Swift Wolf
Manager
40
80
Eager Lion
User
50
51
Eager Tiger
Viewer
45
83
Silent Wolf
User
24
15
Swift Lion
Viewer
34
62
Eager Lion
Manager
21
42
Eager Eagle
Editor
25
35
Bold Tiger
Editor
19
52
Bold Bear
User
42
28
Swift Wolf
Manager
47
9
Swift Bear
Viewer
41
45
Eager Wolf
Editor
35
44
Swift Eagle
Viewer
65
51
Quick Lion
Manager
22
28
Bold Wolf
Editor
30
76
Swift Eagle
Admin
19
26
Eager Eagle
Manager
35
70
Eager Bear
Editor
33
67
Silent Lion
Manager
48
89
Silent Tiger
Manager
62
40
Eager Tiger
Manager
51
82
Silent Lion
Admin
26
16
Bold Eagle
Admin
26
38
Bold Lion
Viewer
49
3
Quick Tiger
Viewer
26
41
Bold Eagle
Editor
50
10
Swift Tiger
Editor
55
6
Silent Lion
Viewer
35
42
GestureResult
Tap a cellSelects the cell. A scroll or a pan selects nothing.
Tap the checkbox of a checkbox cellToggles the value. A tap elsewhere in the cell selects it. A read-only grid does not toggle.
Double-tap a cellStarts 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 headerSelects the column. With headerClickBehavior="sort", it sorts the column.
Tap the number of a row markerChecks only this row.
Tap the checkbox of a row markerToggles this row and keeps the other checks.
Long-press (500 ms) a cell or a headerFires 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 handleExtends 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:

ValueA 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

PropTypeDefault
enableRangeSelectionbooleantrue
enableMultiRangebooleantrue
enableColumnSelectionbooleantrue
enableRowSelectionbooleantrue
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.

On this page