# Kbd

Shows a keyboard key, or a combination of keys, in the style of a key cap.

- **Import:** `import { Kbd, KbdGroup } from "@booleanpress/ui/kbd"`
- **Page:** <https://ui.booleanpress.com/components/kbd> · @booleanpress/ui 0.1.0

## Usage

`Kbd` is one key. Put several in `KbdGroup` for a combination.

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

export function Hint() {
  return (
    <p>
      Press{" "}
      <KbdGroup>
        <Kbd>Ctrl</Kbd>
        <Kbd>K</Kbd>
      </KbdGroup>{" "}
      to search.
    </p>
  )
}
```

Both render the native `kbd` element. `Kbd` is 20 px tall, with a 20 px minimum width, and takes an icon (12 px) as well as text. Inside a tooltip's content it recolours itself for the dark surface.

Kbd only shows a shortcut: it does not register one. Wire the keys with your own handler.

## Examples

### Basic

Single keys.

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

export default function KbdBasic() {
  return (
    <div className="flex items-center gap-2">
      <Kbd>Esc</Kbd>
      <Kbd>Enter</Kbd>
      <Kbd>Tab</Kbd>
    </div>
  )
}
```

### Group

A combination: two keys with a plus sign between them.

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

export default function KbdGroupExample() {
  return (
    <KbdGroup>
      <Kbd>Ctrl</Kbd>
      <span aria-hidden="true" className="text-muted-foreground">
        +
      </span>
      <Kbd>K</Kbd>
    </KbdGroup>
  )
}
```

### In text

Keys inside a sentence.

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

export default function KbdInText() {
  return (
    <p className="max-w-xs text-sm text-muted-foreground">
      Press <Kbd>/</Kbd> to search the email log, or <Kbd>Esc</Kbd> to close the panel.
    </p>
  )
}
```

### In a button

A key hint at the end of a button's label.

```tsx
import { SearchIcon } from "lucide-react"
import { Button } from "@booleanpress/ui/button"
import { Kbd } from "@booleanpress/ui/kbd"

export default function KbdInButton() {
  return (
    <Button variant="outline">
      <SearchIcon />
      Search
      <Kbd className="ms-2">/</Kbd>
    </Button>
  )
}
```

## Accessibility

**Semantics.** The native `kbd` element. `KbdGroup` is also a `kbd`, so a combination is a `kbd` of nested `kbd`s, which HTML allows. Most screen readers read the text as it is, with no extra role.

**Labels.** Its text is its content: write "Ctrl" and "K", not a symbol alone, or add a visually hidden name for symbols such as an arrow or the Command sign. Put a decorative "+" between keys in `aria-hidden`.

**Focus.** Not focusable and ignores the pointer (`pointer-events-none`). It has no keyboard behaviour of its own, so it has no keyboard rows.

**Known limits.**

- Showing a shortcut does not make it available: every action behind a shortcut needs a visible control too (WCAG 2.1.4).
- Key names differ by platform (Ctrl and Command). The product decides which to show.

### Keyboard

| Key | Behaviour |
| --- | --- |

## API

### Kbd

Renders a `kbd` and passes it every other prop.

### KbdGroup

Renders a `div` and passes it every other prop.

Every part takes `className`, merged with its defaults by `cn()`, and `ref`, which reaches the element it renders.

**Data attributes:** `data-slot="kbd"` (Kbd), `data-slot="kbd-group"` (KbdGroup).

## Theming

The fill is `--muted`, the text `--muted-foreground`. In a tooltip it uses `--background` at 20 % on `--background` text.

| Token | Used for |
| --- | --- |
| `--background` | background, text |
| `--muted` | background |
| `--muted-foreground` | text |