# Kbd

Displays a keyboard key or shortcut, with a platform-aware modifier symbol.

Kbd is an open-source component from suiss/ui for React. The @esuiss/ui CLI copies its source into your project, so you own the code.

Source: https://ui.suiss.app/docs/components/kbd

**React**

**Example**

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

export default function KbdDemo() {
  return <Kbd mod>K</Kbd>
}
```

`Kbd` renders a single key as a native `kbd` element in a small rounded box. Set `mod` to prepend the platform's primary modifier: `⌘` on Apple platforms, `Ctrl` elsewhere (`Ctrl+` when the key has children).

Wrap several keys in `KbdGroup` to present a key combination. Use `Kbd` inline in text, in tooltips, or inside an input group addon to hint at a shortcut.

## Installation

### CLI

```bash title="Terminal"
npx shadcn@latest add @esuiss/kbd
```

Works in any project with a `components.json`. See [Installation](https://ui.suiss.app/docs/installation#add-components) for the one-line registry setup. Or use the suiss/ui CLI:

```bash title="Terminal"
npx @esuiss/ui@latest add kbd
```

### Manual

1. Add the [`cn` helper](https://ui.suiss.app/docs/installation#the-cn-helper).

2. Add the pieces it builds on: `use-platform`.

3. Copy the source into `components/ui/kbd.tsx`:

```tsx title="components/ui/kbd.tsx"
"use client"

import { useModifierKey } from "@/hooks/use-platform"
import { cn } from "@/lib/utils"

function Kbd({
  className,
  mod,
  children,
  ...props
}: React.ComponentProps<"kbd"> & { mod?: boolean }) {
  const modifier = useModifierKey(children != null)

  return (
    <kbd
      data-slot="kbd"
      className={cn(
        "pointer-events-none inline-flex h-5.5 max-md:hidden w-fit min-w-5.5 items-center justify-center gap-1 rounded-sm bg-muted px-1.5 font-sans text-xs text-muted-foreground select-none in-data-[slot=input-group]:bg-background in-data-[slot=tooltip-content]:bg-background/20 in-data-[slot=tooltip-content]:text-background dark:in-data-[slot=tooltip-content]:bg-background/10 [&_svg:not([class*='size-'])]:size-3",
        className
      )}
      {...props}
    >
      {mod && modifier}
      {children}
    </kbd>
  )
}

function KbdGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <kbd
      data-slot="kbd-group"
      className={cn("inline-flex items-center gap-1 max-md:hidden", className)}
      {...props}
    />
  )
}

export { Kbd, KbdGroup }
```

4. Update the import paths to match your project.

## Usage

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

```tsx
<Kbd mod>K</Kbd>
```

Pass the key label as children. Use `mod` instead of hard-coding `⌘` or `Ctrl` so the hint matches the user's platform. Icons placed inside `Kbd` are sized to `size-3` unless they set their own `size-*` class.

## Examples

### Modifiers

The platform modifier alongside common modifier and named keys such as Shift, Option, Control, Esc and Tab.

**Example**

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

export default function KbdModifiers() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Kbd mod />
      <Kbd>⇧</Kbd>
      <Kbd>⌥</Kbd>
      <Kbd>⌃</Kbd>
      <Kbd>Esc</Kbd>
      <Kbd>Tab</Kbd>
    </div>
  )
}
```

### Group

Key combinations wrapped in `KbdGroup`, both inline in a sentence and on their own.

**Example**

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

export default function KbdGroupExample() {
  return (
    <div className="text-muted-foreground flex flex-col items-start gap-3 text-sm">
      <p>
        Use{" "}
        <KbdGroup>
          <Kbd mod />
          <span>+</span>
          <Kbd>B</Kbd>
        </KbdGroup>{" "}
        to toggle the sidebar.
      </p>
      <KbdGroup>
        <Kbd mod />
        <Kbd>⇧</Kbd>
        <Kbd>P</Kbd>
      </KbdGroup>
    </div>
  )
}
```

### With icon

Keys that use an icon instead of, or next to, a text label.

**Example**

```tsx
import { ArrowElbowDownLeftIcon, CommandIcon } from "@phosphor-icons/react"
import { Kbd } from "@/components/ui/kbd"

export default function KbdWithIcon() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Kbd>
        <CommandIcon />
        K
      </Kbd>
      <Kbd>
        <ArrowElbowDownLeftIcon />
      </Kbd>
    </div>
  )
}
```

### In input group

A shortcut hint placed in the trailing addon of a search input group.

**Example**

```tsx
import { MagnifyingGlassIcon } from "@phosphor-icons/react"
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@/components/ui/input-group"
import { Kbd } from "@/components/ui/kbd"

export default function KbdInInputGroup() {
  return (
    <div className="w-80">
      <InputGroup>
        <InputGroupInput placeholder="Search..." />
        <InputGroupAddon>
          <MagnifyingGlassIcon />
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">
          <Kbd mod>K</Kbd>
        </InputGroupAddon>
      </InputGroup>
    </div>
  )
}
```

## API Reference

- `Kbd`
- `KbdGroup`
- `Kbd`

### Kbd

Renders one key as a `kbd` element, optionally prefixed with the platform modifier.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mod` | `boolean` | - | Prepends the platform's primary modifier key: `⌘` on macOS and iOS, `Ctrl` on other platforms. |

Also accepts the props of `React.ComponentProps<"kbd">`.

### KbdGroup

Groups several keys into a single inline key combination.

Also accepts the props of `React.ComponentProps<"div">`.

## Accessibility

- Keys render as native `kbd` elements, so the text is announced as keyboard input.
- `Kbd` and `KbdGroup` are hidden below the `md` breakpoint, so do not rely on them as the only place a shortcut is documented.
- `Kbd` sets `pointer-events-none`; clicks pass through to the surrounding control, as in an input group addon.

## Notes

- Styling hooks: `data-slot="kbd"` and `data-slot="kbd-group"`.
- Platform detection reads `navigator` through `useSyncExternalStore`; during server rendering the non-Apple modifier is used.
- Inside an input group or tooltip content, `Kbd` adapts its background and text colors automatically.
- Uses the `muted`, `background` and `muted-foreground` colors.