ShortcutRecorder

Records key combinations into key caps with conflict warnings, plus Kbd, ShortcutKeys and a searchable ShortcutList cheatsheet.

When to use

• Settings where people customise keyboard shortcuts.
• ShortcutList for a keyboard-shortcuts dialog or help page; ShortcutKeys and Kbd for showing shortcuts inline in menus, tooltips and docs.
• Not for typing text; this captures key chords only.

Usage

import { ShortcutRecorder } from "@/components/iris/shortcut-recorder/shortcut-recorder";

const [shortcut, setShortcut] = useState("mod+shift+k"); // "mod" is ⌘ on Mac, Ctrl elsewhere
h(ShortcutRecorder, {
  label: "Move to Reply later",
  value: shortcut,
  onValueChange: (next, { replaced }) => {
    setShortcut(next); /* unbind replaced?.label */
  },
  bindings: [{ shortcut: "mod+k", label: "Open command palette" }],
});

h(ShortcutList, {
  label: "Keyboard shortcuts",
  groups: [{ label: "General", items: [{ label: "New message", shortcut: "mod+shift+n" }] }],
});
h(ShortcutKeys, { shortcut: "mod+shift+p", size: "sm" });
h(Kbd, { size: "sm" }, "Esc");

Props

ShortcutRecorder

Prop	Type	Default	Description
label	string	required	Field label; the accessible name also speaks the shortcut.
hideLabel	boolean	–	Label for screen readers only.
value / defaultValue	string | null	–	Normalised shortcut such as "mod+shift+k".
onValueChange	(value, { replaced? }) => void	–	replaced is the binding taken over after "Use anyway".
resetValue	string | null	defaultValue	What the reset button restores.
bindings	{ shortcut; label }[]	–	Shortcuts in use; recording one asks first.
warnReserved	boolean	true	Also warn about browser/system combinations such as ⌘W.
requireModifier	boolean	true	Require ⌘, Ctrl or ⌥ (function keys always allowed).
platform	"mac" | "other"	detected	Platform used for symbols.
placeholder / description / disabled / id / className	–	–	Field copy and state.

ShortcutList: groups: { label; items: { label; shortcut; keywords? }[] }[] (required), label, searchable, searchPlaceholder, highlightPressed (default on), platform, className.

ShortcutKeys: shortcut (required), platform, pressed (held key ids), size: "sm" | "md", className.

ShortcutKbd (also exported as the deprecated alias Kbd): children (required), pressed, size: "sm" | "md", plus HTML attributes.

Notes

• Keyboard: Enter or Space starts recording; Escape cancels; Backspace/Delete clears; Tab stops without capturing Tab. In the list search, Escape clears the query.
• The recorder is a button with aria-pressed while recording; status and conflicts go through a polite live region and real buttons. ShortcutKeys gives a spoken label.
• highlightPressed adds window key listeners; turn it off for very long lists. The list switches to two columns at 520px.
• Reduced motion removes scale, stagger and height springs, leaving fades.