---
title: KbdGroup
description: Display a multi-key shortcut with shared styling.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# KbdGroup

> Display a multi-key shortcut with shared styling.

## Anatomy

```text
KbdGroup [component; slot=root; <kbd>]
└── item [slot]
```

Separator content is inline and is not a theme slot.

## Usage

Use KbdGroup to display keys pressed together, such as Ctrl + K. It renders notation only; the
application owns the shortcut listener. For a single keycap, use [Kbd](https://moraine.subf.dev/components/kbd.md).

```tsx
import { KbdGroup } from 'moraine'

export function Example() {
  return <KbdGroup items={['Ctrl', 'K']} />
}
```

### Key labels

Each item is a key string, resolved like the `value` of [Kbd](https://moraine.subf.dev/components/kbd.md), or a Kbd props
object with `value`. Known aliases resolve to symbol notation and spoken names. Use an object to set
`aria-label`, `symbol`, or `translations` for one key. The group's `size` and `variant` apply to
every key.

```tsx
<KbdGroup items={['meta', 's']} />
<KbdGroup items={[{ value: 'meta', translations: { meta: 'Command' } }, 'K']} />
```

### Separator

`separator` defaults to `"+"` and accepts a string or number for inline notation. For custom JSX,
pass a component that receives the `index` of the key it follows; each position mounts its own
instance. It is unrelated to the layout [Separator](https://moraine.subf.dev/components/separator.md).

```tsx
<KbdGroup items={['Ctrl', 'Shift', 'K']} separator="/" />
<KbdGroup items={['Ctrl', 'K']} separator={() => <span class="text-muted-foreground">then</span>} />
```

## Examples

### Label save and format shortcuts

Place the group beside the command it describes. Alias keys resolve to platform symbols by default.

```tsx
import { KbdGroup } from 'moraine'

export function KbdGroupUsage() {
  return (
    <div class="flex flex-col gap-3">
      <div class="flex gap-2 items-center">
        <span class="text-sm text-muted-foreground">Save document:</span>
        <KbdGroup items={['meta', 's']} />
      </div>
      <div class="flex gap-2 items-center">
        <span class="text-sm text-muted-foreground">Format document:</span>
        <KbdGroup items={['shift', 'alt', 'f']} />
      </div>
    </div>
  )
}
```

### Show a chord with a custom divider

Pass a `separator` component when the notation should not use `+`.

```tsx
import { KbdGroup } from 'moraine'

export function CustomSeparator() {
  return (
    <KbdGroup
      items={['Ctrl', 'Shift', 'K']}
      separator={() => <span class="text-muted-foreground">/</span>}
    />
  )
}
```

## API Reference

### Props

Props for the KbdGroup component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items* | (keyof typeof KBD_KEY_ALIASES \| (string & {}) \| {<br>  /** Localized spoken names for key aliases, keyed by alias such as `meta` or `escape`. Used as the `aria-label` when `value` is an alias and `aria-label` is not set. */<br>  translations?: Translations;<br>  /** The key to display. A name matching a built-in alias, compared case-insensitively<br>(`meta`, `ctrl`, `shift`, `escape`, `arrowup`, ...), shows its symbol or short label, such as `⌘` for<br>`meta` or `Esc` for `escape`, unless `symbol` is `false`. Any other string renders as written, such as `K` or `F5`.<br>Nothing renders for an empty string. */<br>  value: Key;<br>  /** Whether to resolve known key aliases to symbols. */<br>  symbol?: boolean;<br>  /** Accessible label for the keycap. Overrides the spoken name of a key alias; plain keys have no `aria-label` unless set. */<br>  aria-label?: string;<br>})[] | — | Keys displayed in order as one simultaneous shortcut. Each item is a key string, resolved<br>like `Kbd` `value`, or a `Kbd` props object to customize one key. The group renders nothing when empty. |
| separator | string \| number \| Component<SeparatorRenderProps> \| undefined | '+' | Text between keys, or a component rendered between each pair of keys. The component receives the<br>`index` of the key it follows. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| variant | 'default' \| 'outline' \| 'invert' \| undefined | 'default' | Visual style variant applied to rendered shortcut keys. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`items` example**

```tsx
import { KbdGroup } from 'moraine'

<KbdGroup items={['meta', { value: 'K', 'aria-label': 'letter K' }]} />
```

**`separator` example**

```tsx
import { KbdGroup } from 'moraine'

<KbdGroup
  items={['g', 'i']}
  separator={(props) => <span aria-hidden="true">then {props.index}</span>}
/>
```
