Kbd
Keycaps for a keyboard shortcut, with mod shown as Command on Apple platforms and Ctrl elsewhere.
import { Kbd } from "@butteryui/core";Demo
When to use it
Use it for
- Showing a shortcut next to a menu item, in a tooltip or in help text
- Platform-aware shortcuts:
keys={["mod", "K"]}
Not for
- Code or file names: use code
- Anything people press: a keycap is a label, not a button
Examples
Help text
A hint that names the key to press.
Press
Escto leave crop mode.
Menu shortcut
Commands with their shortcuts at the end of each row, as in a menu; the keys work while focus is in the list.
1 copy of the slide
Variants and states
Shortcuts
mod reads as ⌘ on Apple platforms and Ctrl elsewhere; screen readers hear key names.
Props
Kbd
| Prop | Type | Default | Description |
|---|---|---|---|
keys | readonly KbdKey[] | A shortcut's keys in order, each drawn as its own cap: ["mod", "Z"] shows ⌘ Z on Apple platforms and
Ctrl Z elsewhere. Without it, the children are a single cap. |
It also takes ComponentPropsWithRef<"kbd">.
Also exported
| Export | Description |
|---|---|
ariaKeyShortcuts(shortcut: Shortcut, apple: boolean): string | A shortcut as aria-keyshortcuts writes it: "mod+n" is "Meta+N" on Apple platforms and "Control+N" elsewhere. |
shortcutKeys(shortcut: Shortcut): KbdKey[] | A shortcut's keys as caps for Kbd: "mod+shift+z" becomes ["mod", "shift", "Z"]. |
useApplePlatform(): boolean | Whether this runs on an Apple platform, where mod is ⌘ rather than Ctrl. False while rendering on a server. |
Accessibility
Renders nested kbd elements, one per key. Symbols such as ⌘ and ⇧ carry visually hidden names, so screen readers say Command and Shift.
It takes no keyboard input of its own.
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
Each key is a cap --bt-h-badge (20px) tall and at least as wide, with 4px of padding either side, in the kbd text role; a shortcut's caps sit 2px apart in a row that never wraps or shrinks. A keycap is a label, with no hit area.