Kbd

In a menu row

In a tooltip

⌘K

In a field

TSX

import { KbdGroup } from "@arcadia/ui";

<KbdGroup keys="mod+n" size="sm" />

keys takes display keys (["⌘", "N"], each split at its modifiers), a glyph string ("⌘⇧K") or a spec ("mod+shift+k", which renders ⌘ on macOS and Ctrl elsewhere). key is the boxed cap; plain is the unboxed quiet hint used in pills, fields and menus.

Kbd is visual only. Inside a control, mark it aria-hidden and put the shortcut on the control with aria-keyshortcuts, using ariaKeyShortcuts(keys), so the name stays the label. Button hint, MenuItem shortcut and IconButton shortcut do both for you.

Examples

Caps

Boxed caps for a shortcut on its own; plain for a hint inside something else. Multi-character keys widen with padding.

⌘K⌘⇧PEsc⇧Tab

import { Kbd, KbdGroup } from "@arcadia/ui";

<KbdGroup keys="⌘K" />
<KbdGroup keys="mod+shift+p" />
<Kbd>Esc</Kbd>
<Kbd variant="plain">⇧Tab</Kbd>

Legend

The keys a surface listens to, as one quiet footer line: caps, then a verb. Pickers, palettes and popovers all teach keys with KeyLegend, so a key reads the same everywhere.

import { KeyLegend } from "@arcadia/ui";

<KeyLegend hints={[
  { keys: ["↑", "↓"], label: "Move" },
  { keys: "⏎", label: "Open" },
  { keys: ["⌘[", "⌘]"], label: "Filter" },
  { keys: "Esc", label: "Close" },
]} />

Parsing

One parser feeds key caps, tooltips and aria-keyshortcuts: the spec, its display keys and its ARIA value.

SpecDisplay keysARIA

"⌘⇧K"⌘⇧KMeta+Shift+K

"mod+shift+k"⌘⇧KMeta+Shift+K

"⇧Tab"⇧TabShift+Tab

"^Tab"⌃TabControl+Tab

"esc"EscEscape

import { KbdGroup, ariaKeyShortcuts, shortcutKeys } from "@arcadia/ui";

function Parsing() {
  const specs = ["⌘⇧K", "mod+shift+k", "⇧Tab", "^Tab", "esc"];
  return (
    <div {...sx("cmp-parse", cmp.parse)}>
      <span {...sx("cmp-parse-head", cmp.parseHead)}>Spec</span>
      <span {...sx("cmp-parse-head", cmp.parseHead)}>Display keys</span>
      <span {...sx("cmp-parse-head", cmp.parseHead)}>ARIA</span>
      {specs.map((spec) => (
        <div key={spec} style={{ display: "contents" }}>
          <code>{JSON.stringify(spec)}</code>
          <KbdGroup keys={shortcutKeys(spec)} size="sm" />
          <code>{ariaKeyShortcuts(spec)}</code>
        </div>
      ))}
    </div>
  );
}

A stray caret is read as Control and named keys take one spelling, so ^Tab and esc still draw right.

Size and variant

KeyPlainSmall

⌘KEsc⌘⇧P

Medium

⌘KEsc⌘⇧P

Kbd renders <kbd> and KbdGroup a row of them; both are text, never focusable, and have no keys of their own. Glyphs like ⌘ and ⇧ are read inconsistently by screen readers, which is why a shortcut belongs on its control as aria-keyshortcuts ("⌘⇧K" becomes Meta+Shift+K) while the caps stay aria-hidden.

Showing a shortcut doesn't bind it: the key handler is yours. Prefer mod in specs so the same shortcut shows ⌘ on macOS and Ctrl elsewhere, and avoid keys a screen reader or the browser already uses.

size: "sm" | "md"Default "md"; md 18px caps, sm 16px caps (tooltips, dense rows).
variant: "key" | "plain"Default "key"; key: a boxed key cap. plain: the unboxed quiet hint used in pills and menus.

Rest props go to <kbd> props and render.

keysrequired: string | readonly string[]; ["⌘","N"], "⌘N", or a spec like "mod+shift+k" (see shortcutKeys).
size: "sm" | "md"Default "md"
variant: "key" | "plain"Default "key"; key: a boxed key cap. plain: the unboxed quiet hint used in pills and menus.
className: string; The part name a parent gives the group it renders (ui-menu-item-shortcut), for its own rules.

Rest props go to <span> props and render.

hintsrequired: readonly KeyHint[]

Rest props go to <div> props and render.

Usage

Examples

Caps

Legend

Parsing

Matrix

Accessibility

API reference

Kbd

KbdGroup 4 props

KeyLegend 1 prop