Shortcut recorder

In FORMA

• Liegt in kit/arc/shortcut-recorder und ist über @/forma/arc/shortcut-recorder/shortcut-recorder erreichbar.
• Farbe, Ecken, Höhen, Abstände, Tiefe, Schrift und Tempo kommen aus der Richtung (core/arc-bridge.ts); Arc behält Verhalten, Tastatur und Federn.

When to use

• Settings pages where people remap keyboard shortcuts.
• A keyboard shortcut cheatsheet or help dialog, with ShortcutList.
• Inline key hints in menus, tooltips, and docs, with ShortcutKbd or ShortcutKeys.

When not to use

• Use ShortcutKbd alone when shortcuts are fixed and only need to be shown.
• Use command-palette to let people run actions by name rather than bind keys.
• Avoid it on touch-only products where no hardware keyboard is expected.

Usage

import { useEffect, useState } from "react";
import { ShortcutRecorder, matchesShortcut, usePlatform } from "@/forma/arc/shortcut-recorder/shortcut-recorder";

export function SearchShortcut() {
  const platform = usePlatform();
  const [shortcut, setShortcut] = useState<string | null>("mod+k");

  useEffect(() => {
    if (!shortcut) return;
    const onKey = (event: KeyboardEvent) => {
      if (matchesShortcut(event, shortcut, platform)) { event.preventDefault(); openSearch(); }
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [platform, shortcut]);

  return (
    <ShortcutRecorder
      label="Open search"
      value={shortcut}
      onValueChange={setShortcut}
      resetValue="mod+k"
      bindings={[{ shortcut: "mod+p", label: "Print" }]}
    />
  );
}

API reference

ShortcutRecorder

A field that records a keyboard shortcut, lights held keys as caps, and asks before taking a combination already in use.

ShortcutList

A searchable, grouped shortcut cheatsheet. Holding a modifier lights its caps and fades rows that do not use it.

ShortcutKeys

A shortcut drawn as key caps in platform order, with a spoken label.

ShortcutKbd

A single key cap for inline copy and menus. Also exported as Kbd, a deprecated alias.

matchesShortcut / formatShortcut / usePlatform / usePressedKeys

Helpers: test a keydown against a stored shortcut, format it as "⌘⇧K" or "Ctrl+Shift+K" with a spoken form, read the platform, and track held keys.

Keyboard interactions

Accessibility

• The recorder is a button with aria-pressed while recording, named by the label plus the spoken shortcut, such as "Command Shift K".
• Recording, results, conflicts, and clears are announced through a polite live region; the message row is linked with aria-describedby.
• Key caps are aria-hidden inside the recorder; ShortcutKeys uses role="img" with a spoken aria-label.
• Conflicts offer Use anyway and Cancel as real buttons, and focus returns to the recorder after either.

Motion

• Caps pop in with a small scale and blur, staggered when a finished shortcut settles, and slide on a snappy layout spring as the chord changes.
• A recording dot pulses; the message row opens on a height spring.
• In ShortcutList, groups and rows collapse on a height spring as search filters them.
• Reduced motion removes the scale, stagger, layout slide, and height springs; caps and messages fade.

Responsive behavior

• ShortcutList is a container with a query at 520px that puts groups in two columns; below that they stack.
• The recorder keeps a fixed height and caps wrap within it; hover styles apply only on fine pointers.

Performance

• usePressedKeys adds window keydown and keyup listeners only while enabled; turn off highlightPressed for lists that do not need it.
• ShortcutList filters on every keystroke by building token strings per row; it suits lists of a few hundred shortcuts.

Notes for AI

• Store shortcuts as normalized strings with mod ("mod+shift+k"); they read as ⌘ on Mac and Ctrl elsewhere without a second binding.
• Run bound actions with matchesShortcut in a keydown listener; it compares physical keys, so ⌥K matches "alt+k" rather than "˚".
• Pass every existing binding in bindings, and use details.replaced from onValueChange to unbind the old owner after Use anyway.
• Use ShortcutList for a help sheet and ShortcutKbd for inline hints such as in menus or command-palette rows.

Related

• Command palette: A complete keyboard driven action surface with search, grouped results, and shortcuts.
• Input: A single line field with clear labels and useful states.
• Tooltip: Short supporting text for unfamiliar controls.
• Dropdown menu: A focused list of actions anchored to a trigger.
• Settings page: Account settings with a gliding section nav and a save bar that morphs in as you edit.

Also in special inputs

• Number field: Enter a bounded number with clear increment controls.
• Money input: A currency field with live grouping, stable width, rolling digits, and minor-unit output.
• Phone input: A phone field with a country picker, formatting as you type, and E.164 output.
• Scrub input: A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
• Tag input: Turn short text values into removable tags.
• Mention input: A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.

Guidance for AI tools

Shortcut recorder: Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt