# Kbd

> Keyboard key + shortcut renderer. Platform-aware `mod` glyph, built-in modifier/arrow/enter aliases, outlined + soft variants.

- Package: `@sisyphos-ui/kbd`
- Docs: https://sisyphosui.com/docs/components/kbd
- npm: https://www.npmjs.com/package/@sisyphos-ui/kbd

## Installation

```bash
pnpm add @sisyphos-ui/kbd @sisyphos-ui/core
```

Or use the umbrella package:

```bash
pnpm add @sisyphos-ui/ui
```

## Import

```tsx
import "@sisyphos-ui/kbd/styles.css";
import { Kbd } from "@sisyphos-ui/kbd";
```

## Examples

### Single key

Free-form content rendered inside a single `<kbd>`.

```tsx
import { Kbd } from "@sisyphos-ui/ui";

export function Example() {
  return <Kbd>Esc</Kbd>;
}
```

### Shortcut string

Parsed on `+` and whitespace. Modifier aliases (`cmd`, `ctrl`, `shift`, …) map to glyphs; `mod` resolves to ⌘ on macOS and ⌃ elsewhere.

```tsx
import { Kbd } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Kbd shortcut="cmd+k" />
      <Kbd shortcut="ctrl+shift+p" />
      <Kbd shortcut="alt+tab" />
      <Kbd shortcut="mod+s" />
    </div>
  );
}
```

### Visible separator

`separator` accepts any `ReactNode` — a plus, a dot, a custom divider — rendered between each key.

```tsx
import { Kbd } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Kbd shortcut="cmd+k" separator="+" />
      <Kbd shortcut="ctrl+shift+p" separator={<span style={{ opacity: 0.5 }}>·</span>} />
    </div>
  );
}
```

### Variants

`outlined` (default) has a border and light shadow; `soft` sits on a muted fill.

```tsx
import { Kbd } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Kbd variant="outlined" shortcut="cmd+k" />
      <Kbd variant="soft" shortcut="cmd+k" />
    </div>
  );
}
```

### Sizes

Scales via font-size; chip padding follows in `em`.

```tsx
import { Kbd } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <div className="flex flex-wrap items-end gap-3">
      <Kbd size="xs" shortcut="cmd+k" />
      <Kbd size="sm" shortcut="cmd+k" />
      <Kbd size="md" shortcut="cmd+k" />
      <Kbd size="lg" shortcut="cmd+k" />
      <Kbd size="xl" shortcut="cmd+k" />
    </div>
  );
}
```

### In prose

Drop `<Kbd>` into a paragraph — `vertical-align: middle` keeps it on the text baseline.

```tsx
import { Kbd } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <p>
      Press <Kbd shortcut="cmd+k" /> to open the command menu, or <Kbd>Esc</Kbd> to dismiss it.
    </p>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"outlined" \| "soft"` | `"outlined"` | Chip style. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"sm"` | Size scale. |
| children | `ReactNode` | — | Free-form content; rendered inside a single `<kbd>`. |
| keys | `string[]` | — | Explicit list of keys. Aliases normalized to glyphs. |
| shortcut | `string` | — | Shortcut string split on `+` and whitespace (e.g. `"cmd+k"`). |
| separator | `ReactNode` | — | Rendered between keys. Omit to join them visually. |