skip to content
menu
components · kbd
componentsdata displayreact implementation

kbd

A kbd is a keycap: a small picture of one key, such as esc, that tells people which key to press. A shortcut is several keycaps side by side.

esctabentershiftctrlaltcmdk

when to use

  • To name a key in help text, a tooltip or a menu: esc closes the dialog.
  • To show a shortcut, there or in a list of shortcuts: ctrl + k opens search.

when to use something else

  • For text people type. In “Type storage-01 to confirm”, the name is text that people type, not a key. Show it as code.
  • As a control. A keycap is only a picture of a key: pressing it does nothing. The action itself is a button.

anatomy

  1. Keycap. A small square key with a thin frame and a heavier bottom edge, so it looks like a key you could press. It sits in the line of text, and grows wider for a longer name.
  2. Label. The key's name, in monospace, centred and on one line. It is shown exactly as written: nothing changes its case.

variants and states

A keycap has one look. A shortcut with several keys is several keycaps, which you place yourself, with a joiner between them:

  • A plus, “+”, joins keys that are pressed together: ctrl + k.
  • The word “then” joins keys that are pressed one after another: g then i.
ctrl + kctrl + shift + pg then i

A list of shortcuts is a list of pairs: each action, followed by the keys that do it.

Search
ctrl + k
Open the selected row
enter
Close the dialog
esc

behaviour

  • A keycap only shows a key. It doesn't listen for it: making the shortcut work is up to you.
  • It takes no focus: tab skips it.

The kbd's React page shows what the keycap is built from, and which settings it passes on.

accessibility

  • A screen reader reads a keycap's label as plain text. Most don't say “key”.
  • Write keys as words, such as ctrl, shift, cmd and esc, not as symbols like ⌘ or ⇧. Screen readers name symbols inconsistently, and not everyone recognises them.
  • Keep a visible joiner between keys. Most screen readers read it aloud, as in “ctrl plus k”, and it tells keys pressed together apart from a sequence.
  • A shortcut is never the only way to do something. The same action needs a visible control too.

content

  • Write key names in lowercase, as most keyboards print them: esc, tab, enter, shift, ctrl, alt, cmd, space.
  • One key per keycap. A letter is just the letter: k, not “K”, and not the whole “ctrl+k” in one cap.
  • When a shortcut differs by platform, show the one the reader is on, or both: ctrl on most computers, cmd on those whose keyboard has a command key.

do and don't

do
ctrl + k
One key per cap, joined by a plus: the keys are pressed together.
don't
ctrl+k
The whole shortcut in one cap. It reads as one key with a strange name.
do
cmd + shift + p
Key names written as words read the same for everyone.
don't
⌘ + ⇧ + p
Screen readers name symbols inconsistently, and not everyone knows them.
do

Type storage-01 to confirm.

Text that people type is shown as code.
don't

Type storage-01 to confirm.

A keycap is one key. Text in a keycap looks like a key nobody can find.
  • Code: commands and text that people type.
  • Tooltip: where a control's shortcut is usually shown.
  • Content & voice: how labels and key names are written.

specs

part spec
Keycap A native <kbd>, inline-flex, its label centred. At least 20px wide, 20px tall, padding 0 6px. A 1px --border-2 frame with a 2px bottom edge, --surface-2 fill, square (border-radius: 0).
Label The children. JetBrains Mono 12px, line-height 1, --fg-2, on one line (white-space: nowrap). No text-transform, so it shows as written.
Joiner Not part of the keycap: a + for keys pressed together, or then for a sequence, that you place between keycaps, in muted text (<Text variant="muted">).
List of shortcuts A description list (<dl>): each action in a <Text as="dt">, its keys in a <Text as="dd">.
  • Focus and keys: none. A keycap takes no focus and listens for no key; tab skips it.
  • Attributes: every native <kbd> attribute passes through, and the ref reaches the <kbd>.