gridcn2.0.0
Selection and shortcuts

Global shortcuts

Keep undo, redo, and other grid actions working while focus sits on a toolbar, a side panel, or the page body.

The grid handles keys only while DOM focus is inside it. When focus sits on a custom toolbar, a side panel, or body, Ctrl/Cmd+Z does not reach the grid. DataGridGlobalShortcuts mounts a window listener that keeps undo and redo active at every focus position outside an editable element. Flags add more actions.

Edit a cell, then click the button or the input below (focus leaves the grid) and press Ctrl/Cmd+Z — the undo still lands in the grid. Typing into the input? Ctrl/Cmd+Z undoes the input's text, never the grid.

Name
Score
Silent Tiger
4
Quick Lion
89
Swift Wolf
80
Eager Lion
51
Eager Tiger
83
Silent Wolf
15

The component ships with the core data-grid item. Undo and redo need the Undo and redo add-on.

How it works

DataGridGlobalShortcuts renders nothing. It listens for keydown on the window. Eight checks decide whether an event reaches the grid. The rules run in this order, and the first hit skips the event:

  1. IME composition is in progress.
  2. The event is already defaultPrevented. The page or the grid handled it first.
  3. The target is an editable element: input, textarea, select, or contenteditable. The field keeps its native undo and redo.
  4. The target is inside any grid. The handler of that grid owns the key.
  5. This grid is not the last focused grid that mounts the component.
  6. An edit session is open. The editor owns the key, also in a popup such as the select list.
  7. The key resolves to no enabled action through the effective keymap.
  8. The key press carries neither Ctrl nor Cmd.

When the gate passes, the component runs the action through the same dispatch as the in-grid binding. For undo and redo, that is the undo and redo command of the history add-on. Without the add-on, the key has no binding, rule 7 skips the event, and the browser default runs.

Usage

Mount the component inside the grid. The toolbar sits anywhere outside it:

import {
  DataGrid,
  DataGridBody,
  DataGridGlobalShortcuts,
  DataGridHeader,
  defineColumns,
} from "@/components/data-grid/data-grid";
import {
  useDataGridState,
} from "@/components/data-grid-history/data-grid-history";

type Order = { id: string; customer: string };

const columns = defineColumns<Order>()([
  { id: "customer", header: "Customer", accessorKey: "customer", type: "text" },
] as const);

export function OrdersGrid({ orders }: { orders: Order[] }) {
  const grid = useDataGridState(orders);

  return (
    <>
      {/* a toolbar here, outside the grid */}
      <DataGrid {...grid} className="h-96" columns={columns}>
        <DataGridGlobalShortcuts />
        <DataGridHeader />
        <DataGridBody />
      </DataGrid>
    </>
  );
}

Undo and redo are on by default. Each flag you pass adds its action. A flag set to false removes an action:

import { DataGridGlobalShortcuts } from "@/components/data-grid/data-grid";

export function Shortcuts() {
  return <DataGridGlobalShortcuts selectAll deleteRows />;
}

<DataGridGlobalShortcuts selectAll undo={false} redo={false} /> enables only select all.

FlagEnablesNeeds
undoThe undo binding. Default true.The Undo and redo add-on
redoThe redo bindings. Default true.The Undo and redo add-on
fillDownThe fill-down binding.The Fill handle add-on
fillRightThe fill-right binding.The Fill handle add-on
selectAllThe select-all binding.enableRangeSelection, which defaults to true
insertRowAboveThe insert-row-above binding.createRow
insertRowBelowThe insert-row-below binding.createRow
duplicateRowThe duplicate-row binding.duplicateRow
deleteRowsThe delete-rows binding.A writable grid

Each flagged action runs the same dispatch as its in-grid binding, with the same guards. For example, insertRowBelow does nothing without createRow, and the row actions do nothing in a read-only grid. The listener reads the effective keymap, so a remapped binding applies to the global layer too. See Shortcut remapping.

A flagged action with a bare key binding, such as deleteRows: ["Delete"], stays in the grid (rule 8). In development, the grid warns once about such a binding. To act on a bare key page-wide, add your own window listener that calls api.actions.

Multiple grids

When several grids with the component share a page, the last focused grid owns the shortcut. When focus moves to grid B, undo and redo target the history of B. They stay with B until focus returns to grid A.

A grid without the component never claims the shortcut. If you add the component to one of two grids, the layer does nothing until the user focuses that grid.

The last DOM focus decides. When your app switches tabs without a focus change, call the history API of the active grid, for example grid.history.undo().

Page-wide mod+z

Your app can register its own window-level Mod+Z handler. Both listeners then see the same event. The layer skips an event that is already defaultPrevented, and it calls preventDefault when it handles one. Check event.defaultPrevented in your handler. Register your listener after the grid mounts, in the bubble phase. Otherwise your handler runs first.

Out of scope

  • Copy and paste: the flag list has no clipboard action. For a programmatic paste, call useDataGridClipboard().pasteFromClipboard().
  • Navigation: the flag list has no move or jump action, so the arrow keys stay with the page.
  • Select all by default: the page owns Mod+A until you set the selectAll flag.

On this page