keys/api/hotkey-format

Hotkey format

Modifier syntax, key aliases, and matching rules for @diffgazer/keys hotkey strings.

Hotkeys are strings like "mod+k", "shift+Enter", or "ArrowDown". Each string is parsed once when the handler registers, then matched against keyboard events at dispatch time, and used with useKey.

Modifiers

Joined with +. The last segment is the key, everything before it is a modifier.

Modifier	Maps to
`mod`	`Meta` on Mac, `Ctrl` elsewhere
`ctrl`	`Ctrl`
`shift`	`Shift`
`alt`	`Alt`
`meta`	`Meta`

Key aliases

Alias	Resolved to
`up`	`ArrowUp`
`down`	`ArrowDown`
`left`	`ArrowLeft`
`right`	`ArrowRight`
`esc`	`Escape`
`space`	(space character)

Special rules

Uppercase single letter implies Shift: "G" is equivalent to "shift+g".
Case-insensitive: both the hotkey string and event.key are lowercased before comparison.
Strict modifier matching: all four modifier keys (ctrl, shift, alt, meta) must match exactly. Pressing Ctrl+Shift+K will not match "mod+k" — it would match "mod+shift+k".
Platform detection: mod resolves via navigator.userAgent (cached after first check).

Shifted punctuation aliases

The + delimiter makes shifted punctuation like ? or + ambiguous. Use named aliases.

Strict modifier matching still applies: if a punctuation key requires Shift on the user's layout, include shift+ in the hotkey.

Alias	Resolved to
`question`	`?`
`plus`	`+`
`exclamation`	`!`
`at`	`@`
`hash`	`#`
`dollar`	`$`
`percent`	`%`
`caret`	`^`
`ampersand`	`&`
`asterisk`	`*`
`tilde`	`~`
`pipe`	`\|`
`backslash`	`\`
`slash`	`/`

Examples

tsx

// Simple keys
useKey("Escape", handleClose);
useKey("Enter", handleSubmit);

// With modifiers — use preventDefault for browser-reserved combos
useKey("mod+k", openSearch, { preventDefault: true });
useKey("mod+shift+p", openCommandPalette, { preventDefault: true });

// Arrow keys in containers — preventDefault stops native scrolling
useKey(["ArrowUp", "ArrowDown"], handleNavigate, { preventDefault: true });

// Using aliases
useKey("esc", handleClose);  // same as "Escape"

// Shifted punctuation aliases
useKey("shift+question", openHelp);  // matches Shift+?
useKey("mod+shift+plus", zoomIn, { preventDefault: true });  // matches Cmd/Ctrl with the shifted + key