Kbd

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Write a key or a shortcut with Kbd, in running text, a tooltip or a hint line. Pass the keys pressed together; 'mod' is the command modifier, so ['mod', 'k'] reads ⌘K on Apple platforms and Ctrl+K elsewhere. Kbd puts modifiers in the platform's order and writes a single letter in capitals, as key caps print it.
• A key sits on the plane recessed one step from where it is, at 87.5% of the text around it, in the body face. In a tooltip it is plain text a step quieter, since the tooltip is already its own plane.
• Symbols such as ⌘, ⇧ and the arrows carry their names for screen readers in visually hidden text. Keyboards print the modifiers in English everywhere, so their names stay English; pass labels to translate the arrows.

• Don't write ⌘ or Ctrl yourself: a Mac-only ⌘B is wrong for most readers. Use 'mod' and let Kbd decide.
• Don't make Kbd a button or the only way to learn a shortcut. Name the action in text, and set aria-keyshortcuts on the control the shortcut runs.
• Don't announce a key from aria-label on a kbd element; it has no role to carry a name.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

kbd.surf-kbd (the chord) → kbd per key (glyph + hidden spoken name for symbols), joined by + off Apple platforms

Keyboard and accessibility

• Kbd is text and isn't in the Tab order.
• The server and the first render write the Ctrl form, so hydration matches; an Apple page turns to ⌘ right after.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Kbd, Tooltip } from '@surflane/ui'

<p>Press <Kbd keys={['mod', 'k']} /> to search.</p>
<p><Kbd keys='up' /> <Kbd keys='down' /> Choose · <Kbd keys='enter' /> Open</p>
<Tooltip label='Run the pipeline again' shortcut={['mod', 'shift', 'r']}>
  <Button variant='ghost' size='icon' aria-label='Run the pipeline again'>…</Button>
</Tooltip>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens