# Kbd

> A React kbd component for keyboard shortcuts, shown in the device's notation: ⌘K on a Mac, Ctrl+K everywhere else.

- Type: React component (Data Display)
- Access: Free (the source is open to everyone)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add kbd`
- Docs: https://wingo-ui.com/components/kbd

## Interaction

Pass a combo like mod+k and it prints ⌘ K on Apple devices and Ctrl K elsewhere; screen readers hear "Command K" instead of the glyphs. In the playground, press ⌘K (Ctrl+K) to jump into the search field, use the arrow keys and Enter to move through the results, and press Esc to close the window and again to bring it back. Turn on listen and the caps sink and light up while you hold the real keys. On a phone the keyboard hints hide themselves and a tap opens a result.

## Installation

```bash
npx wingo-ui@latest add kbd
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/kbd.json`

Files:

- `components/ui/kbd.tsx`

Wingo UI dependencies (installed automatically):

- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))
- [useShortcut](https://wingo-ui.com/components/use-shortcut) ([Markdown](https://wingo-ui.com/components/use-shortcut.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))

## Usage

```tsx
import { Search } from "lucide-react"
import { Kbd } from "@/components/ui/kbd"

export function SearchHint() {
  return (
    <div className="flex items-center gap-2 text-sm text-muted-foreground">
      <Search className="size-4" />
      <span className="flex-1">Search listings</span>
      <Kbd shortcut="mod+k" hideOnTouch />
    </div>
  )
}

export function CloseHint() {
  return (
    <p className="text-sm text-muted-foreground">
      Press <Kbd>Esc</Kbd> to close the window, or <Kbd keys={["G", "I"]} separator="then" /> for the Inbox.
    </p>
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children?` | `ReactNode` | `"Esc"` | A single key label, used when there is no shortcut and no keys. Glyphs like ⌘ or ↵ get a spoken name for screen readers. |
| `shortcut?` | `string` | `""` | A combo in mod+k notation: "mod+k", "shift+mod+p", "alt+n", "mod+enter", "/". mod is ⌘ on Apple devices and Ctrl elsewhere. Wins over keys and children; an unparseable value falls back to them. |
| `keys?` | `string[]` |  | One cap per entry, shown as written. For sequences (["G", "I"] with separator "then") and hints that are not one combo (["↑", "↓"]). Used when there is no shortcut. |
| `separator?` | `ReactNode` | `""` | Rendered between caps when they are not combined, like "+" or "then". A word separator is also read out ("G then I"); a symbol is not. |
| `srLabel?` | `string` | `""` | What screen readers hear instead of the caps. By default the combo is spelled out in English ("Shift Command P", "Control K", "G then I"); pass a translation on localized pages. |
| `variant?` | `"soft" \| "outline" \| "solid" \| "ghost"` | `"soft"` | soft is the quiet gray key for hints next to fields and buttons. outline draws a border, solid is a raised key like a real keyboard, ghost is text only for menus and inverted surfaces like tooltips. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Cap height 16 / 20 / 24px with a matching minimum width, 10 / 11 / 12px type and a radius that scales along. |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Semantic color. neutral is the gray key from the design system; the other tones tint the key, and a held key (listen) fills with the tone. |
| `color?` | `string` | `""` | Any CSS color. Replaces the tone in every variant; text on a solid key turns black or white by lightness. |
| `radius?` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"md"` | Corner shape, scaled per size. md is 4 / 5 / 6px; full makes round caps. |
| `combined?` | `boolean` | `false` | The whole combo in one cap (⌘K, Ctrl+K) instead of one cap per key. Reads well in tight rows and menus. |
| `platform?` | `"auto" \| "apple" \| "other"` | `"auto"` | Forces a notation, for docs pages that show both. auto renders the Windows and Linux form on the server and during hydration, then swaps to the device's. |
| `hideOnTouch?` | `boolean` | `false` | Hides the keys on touch screens, where a keyboard hint means nothing. |
| `listen?` | `boolean` | `false` | Caps sink and light up while the matching keys are held on a physical keyboard, and the root gets data-pressed once the whole combo is down. It only watches; it never binds or blocks a key. |
| `classNames?` | `Partial<Record<"key" \| "separator", string>>` |  | Extra classes for every cap (also the single cap) and for the separators. |
| `className?` | `string` |  | Extra classes for the root: the <kbd> for one cap, the group span for several. Merged last. |

## Examples

- **Both notations**: platform forces one: Apple glyphs next to the Windows and Linux words. auto picks the device's.
- **Separate caps or combined**: combined puts the whole combo in one cap, handy in tight rows.
- **Variants and sizes**: soft for hints, outline and solid for docs, ghost as plain text. 16, 20 and 24px caps.
- **Tones, colors and radius**: The tones tint the key, color takes any CSS color, radius scales with the size.
- **Shortcut sheet that listens**: listen: hold a combo and its caps sink, the row lights up once it is all down. A click or a tap runs it too.
- **Inverted and in menus**: variant="ghost" plus a color class, the way tooltips and menu rows show shortcuts.
- **Inside buttons**: As a right icon, aria-hidden with aria-keyshortcuts on the button. hideOnTouch drops the hint on phones.
- **Sequences**: keys with a word separator ("then") for chords like G then I. The word is read out too.

## See also

- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [Shortcuts Dialog](https://wingo-ui.com/components/shortcuts-dialog) ([Markdown](https://wingo-ui.com/components/shortcuts-dialog.md))
- [Command Menu](https://wingo-ui.com/components/command-menu) ([Markdown](https://wingo-ui.com/components/command-menu.md))
- [useShortcut](https://wingo-ui.com/components/use-shortcut) ([Markdown](https://wingo-ui.com/components/use-shortcut.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))

---

Canonical: https://wingo-ui.com/components/kbd
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt