Plugin commands and shortcuts
Look up how plugin commands and keymaps merge with yours, which actions the add-ons own, and which key bindings a plugin keeps.
A plugin adds named commands with its commands member. Its keymap member binds keys to its own commands. The grid merges both with the default keymap and with your props. This table lists the outcome of each conflict:
| Situation | Result |
|---|---|
| Two plugins define the same command name | The first plugin keeps it and the grid drops the later command. A development warning names both plugins. |
Your commands prop defines a name that a plugin defines | Your command wins, with no warning. |
| A plugin command has the name of a built-in action | The grid drops the command and warns in development. |
A plugin keymap names a core action, or a command that the plugin does not define | The grid drops the entry and warns in development. |
A plugin binds a key that the default keymap, your keymap, or an earlier plugin already binds to an action | The grid drops that binding and warns in development. |
A plugin binds a key of the default focusSearch, and your keymap leaves focusSearch out | The plugin takes the key. focusSearch loses it. A development warning names the plugin, unless it is find and replace. |
A plugin command lists keys, and the plugin keymap leaves the command out | The keys bind the command like a plugin keymap entry. |
A plugin keymap lists the keys of one of its commands | The list replaces the bindings of that action, like your keymap prop. List every key the action keeps. |
Commands and keymaps
The commands map of the grid resolves in this order, and a later step wins:
- The commands of the plugins, in array order. The first plugin keeps a name.
- Your
commandsprop.
Each command has the GridCommand shape. Shortcut remapping lists its members. A command receives a GridCommandCtx with these values:
apiis the imperative handle of the grid.cellis the active cell as aCellRef, ornull.viewRowIndexandviewColumnIndexare the view indexes of the active cell.rowis the data row of the active cell. On a row that scroll mode has not loaded yet, it isundefined, andcellholds a placeholder row id thatapicannot resolve.readOnlyis the effective read-only flag of the grid.
When when returns false, the grid ignores the key. It does not call preventDefault, and it does not call run.
The scope member sets the dispatch time of a command. With "grid", the default, it dispatches while no edit session is open. With "editing", it dispatches while a session is open. With "always", it dispatches in both cases.
Add-on actions
The add-ons own eight actions. The core has no key for them.
| Action | Keys | Add-on |
|---|---|---|
undo | Mod+Z | data-grid-history, see Undo and redo |
redo | Mod+Y, Mod+Shift+Z | data-grid-history, see Undo and redo |
fillDown | Mod+D | data-grid-fill, see Fill handle |
fillRight | Mod+R | data-grid-fill, see Fill handle |
openFindReplace | Shift+Alt+Enter | data-grid-find-replace, see Find and replace |
openFind | Mod+F | data-grid-find-replace, see Find and replace |
openKeybindings | ? | data-grid-keybindings, see Shortcut remapping |
openComments | Shift+F2 | data-grid-comments, see Add comments to cells |
An add-on declares its names in GridActions and binds its keys in the keymap of its plugin. Without the add-on, the keys are unbound and the browser default runs.
A command of your own for one of these names needs two steps. Declare the name in GridActions, as Shortcut remapping shows. Then bind a key in your keymap prop. A development warning names a command that has no key.
A plugin's own keymap entries
An entry in the keymap of a plugin needs two things. The plugin must define a command with that name, and the name must not be a core action. Bind a core action through your own keymap prop.
The entry is the full binding list of its action, like the same entry in your keymap prop. The list replaces the bindings of that action, so list every key the action keeps. Keys that differ only in letter case count once. An empty list or undefined unbinds the action.
The grid drops a binding that another action already holds, and warns in development. Your keymap prop keeps its keys. Among plugins, the earlier plugin keeps a key. The default focusSearch binding is the exception. When your keymap leaves out focusSearch, a plugin takes its key, and a development warning names the plugin. The find and replace add-on takes the key with no warning. Set keymap.focusSearch to keep a search key, or to [] to hand the key over.
The keymap resolves in this order, and a later step wins:
DEFAULT_KEYMAP.- The plugin keymaps, in array order.
- Your
keymapprop.
Inside DataGridProvider, useDataGridKeymap() returns the merged keymap without bindings that never match, for a surface outside DataGridRoot such as a shortcut list.
When your keymap entry for fillDown leaves out Mod+D, the key has no binding, and the browser default of the key runs.
This plugin defines openSearchPanel and binds it to Mod+/:
import type { DataGridPlugin } from "@/components/data-grid/data-grid";
export function createSearchPanelPlugin(open: () => void): DataGridPlugin {
return {
name: "my-search-panel",
commands: { openSearchPanel: { run: () => open() } },
keymap: { openSearchPanel: ["mod+/"] },
};
}After this plugin loads, Mod+/ inside the grid runs open. A plugin object attaches to one grid, so call createSearchPanelPlugin() once per grid.