UnflowUI
Components

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

PropTypeDefaultDescription
keysstring[]—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
listenbooleantrueSet to false to render a passive legend even when action is set
allowRepeatbooleanfalseFire action on keydown repeat events

All HTMLDivElement props are forwarded to the container.

Visual display

⌘K
⌘⇧P
⌥F
<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.

to move to open to close
<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 keykeys 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-label built from keys (Mod resolved to the platform key, joined with +). Pass your own aria-label for 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.