Shortcut
Keyboard keycaps with platform-aware symbols. Registers a global hotkey when given an action, or renders as a passive legend.
Overview
Shortcut renders the keyboard combination passed in keys as styled keycaps. With an action, it also registers a global keydown listener that fires action when all keys are held simultaneously. Without one (or with listen={false}), it renders the same keycaps as a passive legend: no listener is registered and no key event is prevented.
Key rendering is platform-aware: on macOS it uses ⌘, ⌥, ⇧; on Windows/Linux it uses Ctrl, Alt, Shift. Use Mod for the platform's primary modifier.
Import
import { Shortcut } from '@unflowio/ui/components/Shortcut';Props
| Prop | Type | Default | Description |
|---|---|---|---|
keys | string[] | — | Required. Key names as KeyboardEvent.key values. Mod is ⌘ on Apple platforms, Ctrl elsewhere |
action | () => void | — | Fired when every key is held. Without it, the keycaps render as a passive legend |
listen | boolean | true | Set to false to render a passive legend even when action is set |
allowRepeat | boolean | false | Fire action on keydown repeat events |
All HTMLDivElement props are forwarded to the container.
Visual display
<Shortcut keys={['Meta', 'k']} />
<Shortcut keys={['Meta', 'Shift', 'p']} />
<Shortcut keys={['Alt', 'f']} />Omit action when you only want the keycaps — e.g. inside a menu item to show which hotkey does the same thing.
Passive legend
Passive keycaps also render the keys a listener never takes: arrows (↑ ↓ ← →) and Esc. Use them for hint rows such as the footer of a command palette.
<span className="flex items-center gap-1.5">
<Shortcut keys={['ArrowUp', 'ArrowDown']} aria-label="Up or down arrow" /> to move
</span>
<span className="flex items-center gap-1.5">
<Shortcut keys={['Enter']} /> to open
</span>
<span className="flex items-center gap-1.5">
<Shortcut keys={['Escape']} /> to close
</span>Active listener
Press ⌘K to trigger the action:
<Shortcut keys={['Mod', 'k']} action={() => openSearch()} />Pressing ⌘K (Ctrl+K on Windows/Linux) anywhere fires action. The keycaps render normally and highlight while the shortcut is held.
Key naming
Follow KeyboardEvent key values:
| Physical key | keys value |
|---|---|
| ⌘ on macOS, Ctrl elsewhere | 'Mod' |
| ⌘ / Windows | 'Meta' |
| Ctrl | 'Control' |
| ⌥ / Alt | 'Alt' |
| ⇧ | 'Shift' |
| Letter | 'k', 'p', etc. (lowercase) |
| Enter | 'Enter' |
| Arrows, Escape | 'ArrowUp', 'Escape', … (passive legends only) |
Integration with ActionCard
Shortcut is used internally by ActionCard when a shortcut prop is provided:
<ActionCard
label="Search"
shortcut={['Mod', 'k']}
listen
onClick={openSearch}
/>ActionCard passes listen down to the internal Shortcut, so you get both the keycaps and the keyboard listener in a single prop.
Accessibility
- The container gets an
aria-labelbuilt fromkeys(Modresolved to the platform key, joined with+). Pass your ownaria-labelfor a friendlier name, e.g. "Up or down arrow". - The keyboard functionality should be documented elsewhere for keyboard-only users (e.g. in a keyboard shortcuts reference page).
- Arrow keys and Escape are never listened for, to avoid interfering with native browser navigation.
ClickAwayEvent
A headless wrapper that detects clicks outside its subtree and fires a callback. The composable primitive used by Popper and Dropdown.
useHotkey
Detects a keyboard combo and fires an action callback. Returns platform-aware visual representations of the keys for use in Shortcut or tooltips.