# Kbd

Displays a keyboard key or shortcut, e.g. inside a search input.

- Category: Core Elements
- Page: https://wunderui.com/components/kbd
- Tier: Free

## Install

```bash
npx wunderui-cli add kbd
```

## Import

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

## Minimal usage

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.

## Usage

```tsx
import { Kbd } from "@/components/ui/kbd"

export function Example() {
  return (
    <div className="flex items-center gap-3 text-sm text-text-secondary">
      <span>Command palette</span>
      <Kbd>⌘K</Kbd>
    </div>
  )
}
```

## 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

- [Tooltip](https://wunderui.com/components/tooltip) for a short label on hover or focus, which draws its own shortcut chip
- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for the shortcut of a menu item, which has its own DropdownMenuShortcut part
- [Badge](https://wunderui.com/components/badge) for a status, a count or a label that is not a key

## Behavior

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

- `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.
- `KbdGroup`: 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.
- `Separator`: 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.
- `KbdHint`: 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.
- `KeyboardHint`

## Best practices

### When to use

- Use Kbd to show a keyboard shortcut next to the action it triggers: in a menu item, a command palette, a tooltip, a search field or a shortcuts panel.

### 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.
- Write the keys the way the platform labels them: ⌘, ⇧ and ⌥ on macOS, Ctrl, Shift and Alt on Windows. Keep one platform per list.
- 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.
- 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 list a shortcut that the app doesn't handle. A hint that does nothing erodes trust in every other hint.
- Don't mix platforms in one list, such as ⌘S next to Ctrl+F. Read the platform and show one set.

## API reference

### Kbd

| Prop | Type | Default | Description |
|---|---|---|---|
| tone | "default" \| "inverse" | "default" | `default` is the light 22 px chip with a border, for pages and cards. `inverse` is the dark 18 px chip with white text, for dark surfaces such as a tooltip. |

Also accepts React.HTMLAttributes attributes.

### KbdGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| separator | React.ReactNode |  | What is drawn between two keys: a plus, a word such as `then`, 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 `Kbd` child that has no tone of its own, and sets the colour of the separator. A `Kbd` inside another element does not receive it. |

Also accepts React.HTMLAttributes attributes.

### KbdHint

| Prop | Type | Default | Description |
|---|---|---|---|
| keys* | string[] |  | The key caps, one string each, such as `["⌘", "K"]` or `["Esc"]`. Required. |
| label* | string |  | The short text after the keys, such as `to search` or `to close`. Required. |
| className | string |  | Extra classes on the hint, for example to change the gap to the next hint. |

### KeyboardHint

| Prop | Type | Default |
|---|---|---|
| keys* | string[] |  |
| label* | string |  |
| className | string |  |

## Examples

### Keys: a character, a symbol group, a named key and the arrows

```tsx
import { Kbd } from "@/components/ui/kbd"

export function Example() {
  return (
    <div className="flex items-center gap-3 text-sm text-text-secondary">
      <span>Jump to search</span>
      <Kbd>/</Kbd>
    </div>
  )
}
```

### Groups: keys side by side, joined by a plus or one after the other

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd"

export function Example() {
  return (
    <div className="flex items-center gap-3 text-sm text-text-secondary">
      <span>New project</span>
      <KbdGroup>
        <Kbd>⇧</Kbd>
        <Kbd>⌘</Kbd>
        <Kbd>P</Kbd>
      </KbdGroup>
    </div>
  )
}
```

### Modifiers: the symbols of macOS and the names of Windows

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd"

export function Example() {
  return (
    <ul className="w-80 max-w-full divide-y divide-border text-sm">
      <li className="flex items-center justify-between py-3">
        <span className="text-text-secondary">Save</span>
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>S</Kbd>
        </KbdGroup>
      </li>
      <li className="flex items-center justify-between py-3">
        <span className="text-text-secondary">Find</span>
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>F</Kbd>
        </KbdGroup>
      </li>
      <li className="flex items-center justify-between py-3">
        <span className="text-text-secondary">Redo</span>
        <KbdGroup>
          <Kbd>⇧</Kbd>
          <Kbd>⌘</Kbd>
          <Kbd>Z</Kbd>
        </KbdGroup>
      </li>
    </ul>
  )
}
```

### Tone: the light chip and the inverse chip for a dark surface

```tsx
import { Kbd } from "@/components/ui/kbd"

export function Example() {
  return (
    <div className="flex items-center gap-3 text-sm text-text-secondary">
      <span>Command palette</span>
      <Kbd>⌘K</Kbd>
    </div>
  )
}
```

### Shortcut hint: key caps with a short label

```tsx
import { KbdHint } from "@wunderui/react"

export function SearchHint() {
  return <KbdHint keys={["⌘", "K"]} label="to search" />
}
```

## In context

### Keyboard shortcuts panel: every action listed with its keys

The keys follow the platform. Each row has the action on the left and its keys on the right, with a divider between rows.

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd"

export function Example() {
  return (
    <section aria-labelledby="shortcuts-title" className="w-full max-w-sm">
      <h3 id="shortcuts-title" className="mb-3 text-base font-semibold text-foreground">Keyboard shortcuts</h3>
      <ul className="divide-y divide-border rounded-xl border border-border bg-card px-4 text-sm">
        <li className="flex items-center justify-between py-3">
          <span className="text-text-secondary">Open command palette</span>
          <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>K</Kbd>
          </KbdGroup>
        </li>
        <li className="flex items-center justify-between py-3">
          <span className="text-text-secondary">Create new project</span>
          <KbdGroup>
            <Kbd>⇧</Kbd>
            <Kbd>⌘</Kbd>
            <Kbd>P</Kbd>
          </KbdGroup>
        </li>
        <li className="flex items-center justify-between py-3">
          <span className="text-text-secondary">Toggle sidebar</span>
          <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>B</Kbd>
          </KbdGroup>
        </li>
        <li className="flex items-center justify-between py-3">
          <span className="text-text-secondary">Save</span>
          <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>S</Kbd>
          </KbdGroup>
        </li>
      </ul>
    </section>
  )
}
```

### Search field with a key hint

The chip sits inside the field as a hint and ignores clicks. The app handles the shortcut itself and announces it to screen readers.

```tsx
import { Kbd } from "@/components/ui/kbd"
import { Input } from "@/components/ui/input"

export function Example() {
  return (
    <div className="relative w-80 max-w-full">
      <Input aria-label="Search" aria-keyshortcuts="/" placeholder="Search projects" className="pr-12" />
      <Kbd aria-hidden className="pointer-events-none absolute top-1/2 right-3 -translate-y-1/2">
        /
      </Kbd>
    </div>
  )
}
```

## For AI agents

`get_component("kbd")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
