Keyboard Shortcuts
KeyGroup displays a keyboard shortcut hint, such as ⌘K or Ctrl+K, next to whatever it's a shortcut for.
import { KeyGroup, maybeMapCombinationKey, OS_ALT_KEY, OS_COMMAND_KEY, OS_CTRL_KEY, MAC_ALT_KEY, MAC_COMMAND_KEY, MAC_CTRL_KEY, WINDOWS_ALT_KEY, WINDOWS_COMMAND_KEY, WINDOWS_CTRL_KEY } from '@balance-web/keyboard-shortcuts';Note
This package is currently in beta. We welcome feedback and contributions to help improve it.
KeyGroup displays a keyboard shortcut hint, such as ⌘K or Ctrl+K, next to whatever it's a shortcut for. It doesn't bind the shortcut itself — pair it with your own key-handling logic (or a hotkeys library) wherever the shortcut is actually triggered.
Usage
Pass an array of key names via keys. Modifier keys (Control, Meta, Alt) are automatically mapped to the current OS's symbol or label.
Variant
variant="tag" renders the keys inside a filled, rounded background instead of plain text.
Non-mapped keys
Keys that aren't Control, Meta or Alt are rendered as-is. Set nonMappedKeyToUpperCase to upper-case them (e.g. k → K) for consistent presentation alongside mapped modifier symbols.
Forcing a platform
os overrides which platform's symbols are used, regardless of the user's actual device — useful for documentation or previews where you want to show a specific platform's shortcut.
API
KeyGroup
| Prop | Type | Default | Description |
|---|---|---|---|
keys | ReactNode[] | — | The keys making up the combination, in display order. String entries matching Control, Meta or Alt are mapped to the current OS's symbol; other ReactNodes are rendered unchanged. |
variant | 'text' | 'tag' | — | 'text' renders plain, muted text; 'tag' renders a filled, rounded badge. |
size | 'xsmall' | 'small' | — | Text size. |
os | 'mac' | 'windows' | the user's detected OS | Forces which platform's key symbols/labels are used. |
nonMappedKeyToUpperCase | boolean | false | Upper-cases string keys that aren't a recognised modifier. |
maybeMapCombinationKey({ key, os, nonMappedKeyToUpperCase })
The mapping function KeyGroup uses internally to turn a single key name into its OS-specific display form. Exported for cases where you need the mapped label without KeyGroup's layout (e.g. inside a tooltip or a custom composition).
Platform key constants
OS_ALT_KEY, OS_CTRL_KEY, OS_COMMAND_KEY resolve to the current OS's symbol (⌥/⌃/⌘ on Mac, Alt/Ctrl/Win on Windows). MAC_ALT_KEY, MAC_CTRL_KEY, MAC_COMMAND_KEY, WINDOWS_ALT_KEY, WINDOWS_CTRL_KEY, WINDOWS_COMMAND_KEY are the platform-specific values maybeMapCombinationKey picks between.