Skip to content
WunderUI

Kbd

Free

Show a keyboard key or a shortcut as a small chip, next to the action it triggers.

npx wunderui-cli add kbd

Playground

Command palette⌘K

Installation

bash
npx wunderui-cli add kbd

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { Kbd, KbdGroup, KbdHint } from "@/components/ui/kbd"
import type { KbdTone } from "@/components/ui/kbd"

Then use it:

tsx
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.

Jump to search/

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.

New project
⇧⌘P

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

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.

Command palette⌘K

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.

⌘Kto search

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.

Ctrl+Shift+P
  • data-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.

  • data-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.

  • data-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.

PropTypeDefaultDescription
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.

PropTypeDefaultDescription
separatorReactNode—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.

PropTypeDefaultDescription
keys requiredstring[]—The key caps, one string each, such as or . Required.
label requiredstring—The short text after the keys, such as or . Required.
classNamestring—Extra classes on the hint, for example to change the gap to the next hint.

PropTypeDefaultDescription
keys requiredstring[]—
label requiredstring—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("kbd")
Installnpx wunderui-cli add kbd

The full library index for assistants is at /llms.txt.