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.
| Symbol | Purpose | Guide |
|---|---|---|
| Binding strings | The syntax of one binding | Shortcut remapping |
keymap | Maps actions to bindings | Shortcut remapping |
commands | Adds a command or replaces a built-in | Shortcut remapping |
useDataGridKeybindings | Mounts the shortcuts dialog | Shortcut remapping |
DataGridKeybindingsDialog | The dialog with the effective keymap | Shortcut remapping |
BindingChips | Renders one binding as keycaps | Shortcut 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.
| Modifier | Matches |
|---|---|
mod | Cmd on macOS, iOS, and iPadOS. Ctrl elsewhere. |
ctrl | The physical Ctrl key on every platform. |
shift | Shift |
alt | Alt 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
typeToReplaceentry, 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:
| Chord | Owner |
|---|---|
| Ctrl+Alt with any key | Windows 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+Space | macOS Spotlight. |
| Ctrl+Space | Toggles the IME on Windows Chinese layouts and switches the input source on macOS. The default selectColumn binding uses it. |
mod+shift+u | Starts Unicode entry in GTK and IBus on Linux. The default insertRowAbove binding uses it. |
| Ctrl+Option with any key | VoiceOver 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 E | Developer tools. E opens them in Firefox and Edge. |
mod+shift with D, M, N, or Delete | Browser 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+Tab | Browser 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.
| Prop | Type | Default | What it does |
|---|---|---|---|
binding | string | required | Sets the binding to render, such as "mod+c". |
className | string | none | Merges 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>
);
}Related
- Shortcut remapping: how to change, add, and remove bindings.
- Keyboard shortcuts: the default bindings.
- Global shortcuts: the opt-in layer outside the grid.
Pinned rows options
Look up the options of useDataGridPinnedRows, aggregateRow, serverAggregateRow, and useDataGridAggregate, plus the reducers and the reporter props.
Status bar options
Look up the props of DataGridStatusBar, the result of useDataGridSelectionStats, and the limits that bound the aggregate walk.