KbdGroup
Keyboard chords rendered as keycaps, with the modifier names of the reader's own platform.
@luc/uiExamples
One chord, two platforms
A chord is one combination rather than a list of symbols: the `+` between the keys belongs to the group and is hidden from a screen reader.
<KbdGroup keys={["⌘", "K"]} />
<KbdGroup keys={["Ctrl", "K"]} />Platform conventions
macOS writes modifiers as glyphs (⌘, ⌥, ⇧) and Windows and Linux spell them (Ctrl, Shift). The component prints the keys it is given rather than choosing for the reader: the source of truth is the reader's own keyboard.
<KbdGroup keys={["⌘", "K"]} />
<KbdGroup keys={["⌥", "⌘", "I"]} />
<KbdGroup keys={["Ctrl", "Shift", "P"]} />
<KbdGroup keys={["Esc"]} />
<KbdGroup keys={["⇧", "↵"]} />Two sizes
`sm` sits inside a caption, a table cell or a menu row; `md` is the default beside a label.
<KbdGroup keys={["⌘", "K"]} size="sm" />
<KbdGroup keys={["⌘", "K"]} />A shortcut list
The definition list is the caller's structure; the single keycap (`Kbd`, in the typography family) is the component to reach for when a chord is not what you need.
- Command menu
- ⌘K
- Toggle inspector
- ⌥⌘I
- Dismiss dialog
- Esc
<dl className="grid grid-cols-[1fr_auto] gap-x-6 gap-y-2">
<dt>Command menu</dt>
<dd><KbdGroup keys={["⌘", "K"]} size="sm" /></dd>
<dt>Toggle inspector</dt>
<dd><KbdGroup keys={["⌥", "⌘", "I"]} size="sm" /></dd>
<dt>Dismiss dialog</dt>
<dd><KbdGroup keys={["Esc"]} size="sm" /></dd>
</dl>Usage
import { KbdGroup } from "@luc/ui";<KbdGroup keys={["⌘", "K"]} />Package setup — peer requirements, the stylesheet and the provider — is on installation.
API
Read from the published TypeScript API, so a prop that is not listed here does not exist and a default that is listed is the one the compiler sees.
| Export | Kind | Signature |
|---|---|---|
KbdGroup | 2 documented props | ({ className, keys, size, ...props }: KbdGroupProps) => import("@types/react").JSX.Element |
KbdGroup props
Type: KbdGroupProps
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
keys | string[] | — | Keys of the chord. Hidden separators keep the announcement clean. |
size? | "sm" | "md" | undefined | — |
Guidelines
Do
- Write the chord the platform actually uses: `⌘` on macOS, `Ctrl` on Windows and Linux, since the component prints exactly the keys it is given.
- Use it where a reader is learning a shortcut — help text, an empty state, a menu hint — not as the only way to find the action.
- Set `size="sm"` inside a caption, a table cell or a menu row.
Don't
- Put the separator in `keys`: the group inserts the `+` itself and hides it from a screen reader.
- Expect the keys to do something: `KbdGroup` is a display, and the application owns the shortcut.
- Translate a key name such as `Esc` or `↵`: it is the label on the reader's own keyboard.
Accessibility
Each key is a `<kbd>` element and the `+` between them is `aria-hidden`, so the chord is announced as one combination instead of a list of symbols. Nothing here is focusable or interactive: a shortcut is only announced by the control that implements it.
Family
Actions
Things a person presses, and the chrome that gathers them.
8 documented entries in this family. Open the family index
Related