gridcn2.0.0
Add-on optionsSelection and shortcuts

Shortcut remapping options

Look up the keymap and commands props, the binding string syntax, and the options of the shortcuts dialog hook, the dialog props, and BindingChips.

The keymap and commands props of DataGridProvider set the key bindings of a grid. The data-grid-keybindings add-on shows them. The steps and the behavior are on Shortcut remapping.

SymbolPurposeGuide
Binding stringsThe syntax of one bindingShortcut remapping
keymapMaps actions to bindingsShortcut remapping
commandsAdds a command or replaces a built-inShortcut remapping
useDataGridKeybindingsMounts the shortcuts dialogShortcut remapping
DataGridKeybindingsDialogThe dialog with the effective keymapShortcut remapping
BindingChipsRenders one binding as keycapsShortcut remapping

Binding strings

A binding is a string of modifiers and one key, joined with +, for example "mod+shift+ArrowUp". A keymap entry maps an action to an array of bindings.

ModifierMatches
modCmd on macOS, iOS, and iPadOS. Ctrl elsewhere.
ctrlThe physical Ctrl key on every platform.
shiftShift
altAlt or Option

The key is a letter, a digit, a function key F1 to F24, a named key, or a printable character. The typed named keys are ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Enter, Escape, Tab, Backspace, and Delete. Other stable key names, such as Insert or MediaPlayPause, bind the same way, in exact case. Write a letter in lowercase, and it matches in either case. Write the space bar as a literal space. The last + separates the key, so the plus key cannot bind.

The modifiers of the key event must equal the modifiers of the binding. The exception is a punctuation key such as ? or /: without shift in the binding, Shift is ignored. A binding that names shift requires it, and wins over a binding without it. A binding with an unknown modifier never matches. A binding with an unknown modifier or key name warns in the browser console in development.

Keymap

keymap has the type Keymap, a partial map from action to KeyBinding[]. The grid merges it over DEFAULT_KEYMAP.

  • An action you leave out keeps its default bindings.
  • An action with an array replaces the default bindings.
  • An action with an empty array has no binding.
  • A defined typeToReplace entry, even an empty one, turns off the implicit printable-key trigger.

Custom commands

A keymap name runs the entry of the same name in commands. An entry named like a built-in action replaces the built-in, and development mode warns about it.

Prop

Type

run and when receive this context:

Prop

Type

Reserved chords

The OS or the browser owns some key combinations. A binding on one of them never fires, or the browser acts on the key too. Do not bind these chords. Two defaults sit on them: where your users' OS takes the chord, give the action another key in keymap:

ChordOwner
Ctrl+Alt with any keyWindows reads it as AltGr. On a German layout, Ctrl+Alt+Q types @, so a mod+alt+q or ctrl+alt+q binding never fires there. The grid matches the typed character, so only a binding on that character, such as mod+alt+@, fires.
Cmd+SpacemacOS Spotlight.
Ctrl+SpaceToggles the IME on Windows Chinese layouts and switches the input source on macOS. The default selectColumn binding uses it.
mod+shift+uStarts Unicode entry in GTK and IBus on Linux. The default insertRowAbove binding uses it.
Ctrl+Option with any keyVoiceOver on macOS, while it runs. For example, Ctrl+Option+Space activates an item.
mod with +, -, or =Browser zoom. The page cannot stop it.
mod+shift with I, J, C, K, or EDeveloper tools. E opens them in Firefox and Edge.
mod+shift with D, M, N, or DeleteBrowser bookmarks, profiles, a private window, and the dialog that clears browsing data.
mod with N, T, or W, mod+shift with T or W, and Ctrl+TabBrowser windows and tabs. Chrome keeps these keys and never sends them to the page, so preventDefault cannot stop them.

useDataGridKeybindings

The hook returns { plugin, open, close }. Put plugin in plugins. open() and close() drive the dialog from your own UI. The plugin defines the openKeybindings command and binds it to ?.

Prop

Type

DataGridKeybindingsDialog

The dialog lists the effective keymap, so it shows your overrides. Mount it inside DataGridProvider. Use it for a controlled dialog or a custom trigger.

Prop

Type

BindingChips

BindingChips renders one keycap for each token of a binding. On the server it renders word names. On macOS, iOS, and iPadOS it switches to glyphs after hydration.

PropTypeDefaultWhat it does
bindingstringrequiredSets the binding to render, such as "mod+c".
classNamestringnoneMerges into the class list of the keycap group.

Example

This sample opens the dialog on ? and adds a second select-all binding:

import {
  DataGridBody,
  DataGridHeader,
  DataGridProvider,
  DataGridRoot,
  defineColumns,
} from "@/components/data-grid/data-grid";
import {
  useDataGridKeybindings,
} from "@/components/data-grid-keybindings/data-grid-keybindings";

type Row = { id: string; name: string };

const rows: Row[] = [{ id: "1", name: "Ada" }];
const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

export function ShortcutsGrid() {
  const keys = useDataGridKeybindings();
  return (
    <DataGridProvider
      defaultData={rows}
      columns={columns}
      keymap={{ selectAll: ["mod+a", "F8"] }}
      plugins={[keys.plugin]}
    >
      <DataGridRoot className="h-80">
        <DataGridHeader />
        <DataGridBody />
      </DataGridRoot>
    </DataGridProvider>
  );
}

On this page