useHotkey
Detects a keyboard combo and fires an action callback. Returns platform-aware visual representations of the keys for use in Shortcut or tooltips.
Overview
useHotkey fires a callback when all the given keys are held at the same time, anywhere on the page. It also returns the keys as ReactNode[], with modifier keys rendered as platform icons, ready to show next to an action.
Shortcut, ActionCard (through Shortcut), ItemNav and CommandPalette use it. Call it directly when you need a global shortcut, with or without the visual badge.
Import
import { useHotkey, resolveModKey } from '@unflowio/ui/hooks/useHotkey';Parameters
| Param | Type | Default | Description |
|---|---|---|---|
keys | string[] | undefined | Keys in MDN KeyboardEvent.key format. Mod is ⌘ on Apple platforms, Ctrl elsewhere |
action | (args?: T) => void | undefined | Callback to fire when the combo is pressed. It is called with no arguments. Without it, nothing is registered |
listen | boolean | true | Enables/disables the listener |
allowRepeat | boolean | false | Fire on key repeat (holding the key) |
Return value
| Field | Type | Description |
|---|---|---|
active | boolean | Whether all keys are currently held |
isHotkeyValid | boolean | Whether the config is complete and listening |
hotkey | ReactNode[] | Platform-rendered key labels. When not listening, arrows and Escape render as ↑ ↓ ← → and Esc |
isMac | boolean | Whether the platform was detected as macOS. false on the server and the first client render |
Usage
Basic global shortcut
const { hotkey } = useHotkey({
keys: ['Mod', 'k'],
action: openSearch,
});
// Render the shortcut badge manually
return <div className="flex gap-1">{hotkey}</div>;Conditional listener
const { isHotkeyValid, hotkey } = useHotkey({
keys: selectedKeys,
action: performAction,
listen: isDialogOpen, // only active while dialog is open
});Check validity before rendering
isHotkeyValid is true only when listen is true, keys is non-empty, and action is defined. Use it to conditionally render the shortcut badge:
{isHotkeyValid && (
<div className="flex gap-0.5">{hotkey}</div>
)}Key naming
Keys follow MDN KeyboardEvent.key:
['Mod', 'k'] // ⌘K on macOS, Ctrl+K elsewhere
['Meta', 'k'] // ⌘K
['Control', 'Shift', 's'] // ⌃⇧S
['Alt', 'p'] // ⌥P (Mac) or Alt+P (Win)
['Enter'] // EnterPlatform awareness
| Key | macOS render | Other platforms |
|---|---|---|
Mod | ⌘ icon | CTRL |
Meta | ⌘ icon | Windows logo icon |
Alt | ⌥ icon | Alt |
Control | ⌃ icon | CTRL |
Shift | ⇧ icon | ⇧ icon |
| Other | The key as written | The key as written |
The platform is read from navigator.platform after mount, so the first render (and server rendering) uses the non-Mac labels.
Blacklisted keys
The following keys are never part of a registered combo. They only render, as glyphs, when the hook is not listening (a passive legend):
- Arrow keys (
ArrowDown,ArrowUp,ArrowLeft,ArrowRight) Escape,(comma — used as a separator in some key string formats)
These conflict with focus management (arrows, Escape) and could cause unexpected behavior if registered globally.
Normalization
Keys are lowercased and sorted before registration. This means:
useHotkey({ keys: ['Control', 'K'], action })
useHotkey({ keys: ['k', 'control'], action })
// Both register the same comboresolveModKey
resolveModKey(key: string, isMac: boolean): stringReturns 'Meta' on Apple platforms and 'Control' elsewhere when key is Mod (any case), and key unchanged otherwise. Use it to build an accessible name for a shortcut, as Shortcut does for its aria-label:
const { hotkey, isMac } = useHotkey({ keys, action });
const label = keys.map((key) => resolveModKey(key, isMac)).join('+');Implementation notes
All useHotkey calls share one keydown/keyup listener on window. Every registered entry whose keys match fires, so two components listening for the same combo both run their action; use listen to keep only one active. A match calls preventDefault() and stopPropagation() on the event, so the browser's own shortcut for that combo doesn't run.
Held keys are cleared when Meta is released, when the window loses focus and when the tab is hidden, so a combo never stays stuck after switching apps.