Kbd
FreeShow a keyboard key or a shortcut as a small chip, next to the action it triggers.
npx wunderui-cli add kbdPlayground
Installation
npx wunderui-cli add kbdWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Kbd, KbdGroup, KbdHint } from "@/components/ui/kbd"
import type { KbdTone } from "@/components/ui/kbd"Then use it:
import { Kbd, KbdGroup } from "@/components/ui/kbd"
export function CommandHint() {
return (
<div className="flex items-center gap-3 text-sm text-text-secondary">
<span>Open the command palette</span>
<KbdGroup separator="+">
<Kbd>Ctrl</Kbd>
<Kbd>K</Kbd>
</KbdGroup>
</div>
)
}Expected result: You see the text Open the command palette followed by two 22 px key chips, Ctrl and K, with a + between them.
When to use
Use Kbd for
- The shortcut of an action, shown beside its label in a menu, a command palette or a shortcuts panel
- A key hint inside a search field or a button, such as / or ⌘K
- A combination or a sequence of keys in help text and documentation
Use something else for
- Tooltip for a short label on hover or focus, which draws its own shortcut chip
- Dropdown Menu for the shortcut of a menu item, which has its own DropdownMenuShortcut part
- Badge for a status, a count or a label that is not a key
Keys
One chip holds one key: a character, a symbol group such as ⌘K, or a name such as Esc. It is 22 px high and grows with its text. On a muted or subtle field the chip takes the card fill so it stays visible, and in a pill field it is a pill too.
Groups
KbdGroup lines up several keys with a 4 px gap. A separator puts a plus or a word between them, for a combination or a sequence.
Modifiers
Write keys the way the platform labels them: symbols on macOS, names joined by plus on Windows and Linux. Keep one platform per list.
- Save⌘S
- Find⌘F
- Redo⇧⌘Z
- SaveCtrl+S
- FindCtrl+F
- RedoCtrl+Shift+Z
Tone
The default chip is light, for pages and cards; the inverse chip is dark, for surfaces such as a tooltip. Set the tone on the group and every key follows.
Shortcut hint
KbdHint is a key or a combination with a short label after it, such as ⌘ K to search. It is the legend for the foot of a command menu or a search field. The caps are 22 px high with a muted fill, the label is tertiary text, and it replaces KeyboardHint.
Behavior and motion
What the chip does with its content, its group, its tone and motion.
- Element
- Kbd renders a native kbd element and KbdGroup a div. Neither is focusable or interactive, and screen readers read a chip as plain text.
- Size
- The default chip is 22 px high with a 20 px minimum width and 6 px side padding, in 12 px medium text. The inverse chip is 18 px high with an 18 px minimum width and 5 px padding, in 12 px semibold.
- Grouping
- KbdGroup is an inline flex row with a 4 px gap. The separator sits between two keys, never after the last one, and a group with neither tone nor separator just lines the keys up.
- Tone
- The group's tone is applied to each direct Kbd child that has none of its own, so one prop turns a whole combination inverse. The separator turns white with it.
- Theme
- The default chip uses the subtle, border and secondary text tokens; the inverse chip uses the tooltip key token and white. Both follow the theme and dark mode with no extra class.
- Motion
- The chip has no state and no transition. Nothing in it moves.
- Reduced motion
- There is no animation to reduce, so reduced motion changes nothing.
Anatomy
A key chip and the group that lines chips up. The figure shows three keys joined by a separator; the numbers name the parts in the list below.
- 1data-slot="kbd"
One key chip, 22 px high with a subtle fill, a border and a 4 px corner, holding a single key or a short symbol group like ⌘K. The inverse tone is a dark 18 px chip for surfaces like tooltips.
- 2data-slot="kbd-group"Optional
Lines up several keys in a row with a 4 px gap. Its tone passes on to every direct Kbd child that has none of its own, and the separator is drawn between two keys.
- 3data-slot="kbd-separator"Optional
The text between two keys: a plus for a combination, a word such as then for a sequence. It is muted on light surfaces, white on inverse, and absent after the last key.
- data-slot="kbd-hint"Optional
The shortcut hint: key caps with a short label after them, for the foot of a command menu or next to a search field. The caps are 22 px high with a muted fill and 11 px text, the label is tertiary text. It replaces KeyboardHint.
- Optional
Best practices
- Do
Put one key in each Kbd and join keys with KbdGroup. Use a plus separator when the keys read as one combination, such as Ctrl + Shift + P, and a word like then for a sequence.
- Do
Write the keys the way the platform labels them: ⌘, ⇧ and ⌥ on macOS, Ctrl, Shift and Alt on Windows. Keep one platform per list.
- Do
Use the inverse tone when the shortcut sits on a dark surface, and set it on the KbdGroup so every key follows. A Kbd wrapped in another element doesn't get the group's tone.
- Do
Set aria-keyshortcuts on the control the shortcut triggers. The chip is text for the eye; the attribute tells assistive technology.
- Don’t
Don't use Kbd for decoration or for text that is not a key. It is a hint, not a button, and it doesn't run the shortcut.
- Don’t
Don't list a shortcut that the app doesn't handle. A hint that does nothing erodes trust in every other hint.
- Don’t
Don't mix platforms in one list, such as ⌘S next to Ctrl+F. Read the platform and show one set.
API reference
One table per part. Kbd also takes every attribute of the kbd element it renders, and KbdGroup those of its div, such as className, id and aria-label. KbdHint renders a span and takes only the props listed under it.
One key chip, 22 px high with a subtle fill, a border and a 4 px corner, holding a single key or a short symbol group like ⌘K. The inverse tone is a dark 18 px chip for surfaces like tooltips.
| Prop | Type | Default | Description |
|---|---|---|---|
| tone | "default" | "inverse" | "default" | is the light 22 px chip with a border, for pages and cards. is the dark 18 px chip with white text, for dark surfaces such as a tooltip. |
Lines up several keys in a row with a 4 px gap. Its tone passes on to every direct Kbd child that has none of its own, and the separator is drawn between two keys.
| Prop | Type | Default | Description |
|---|---|---|---|
| separator | ReactNode | — | What is drawn between two keys: a plus, a word such as , or any node. Nothing is drawn after the last key. Leave it out to line the keys up with only the 4 px gap. |
| tone | "default" | "inverse" | — | Passed on to every direct child that has no tone of its own, and sets the colour of the separator. A inside another element does not receive it. |
The shortcut hint: key caps with a short label after them, for the foot of a command menu or next to a search field. The caps are 22 px high with a muted fill and 11 px text, the label is tertiary text. It replaces KeyboardHint.
| Prop | Type | Default | Description |
|---|---|---|---|
| keys required | string[] | — | The key caps, one string each, such as or . Required. |
| label required | string | — | The short text after the keys, such as or . Required. |
| className | string | — | Extra classes on the hint, for example to change the gap to the next hint. |
| Prop | Type | Default | Description |
|---|---|---|---|
| keys required | string[] | — | |
| label required | string | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("kbd")npx wunderui-cli add kbdThe full library index for assistants is at /llms.txt.