Xzero UI
Pro library
ComponentsShortcut recorder

Shortcut recorder

Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

$ pnpm dlx shadcn@4.23.0 add @xzero-ui/shortcut-recorder
Live · keyboard ready

When to use

When not to use

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/shortcut-recorder

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { useEffect, useState } from "react";
import { ShortcutRecorder, matchesShortcut, usePlatform } from "@/components/xzero/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.

PropTypeDefaultDescription
label (required)string–Field label.
hideLabelbooleanfalseKeeps the label for screen readers only.
valuestring | null–Controlled shortcut, such as "mod+shift+k". mod is Command on Apple platforms and Ctrl elsewhere.
defaultValuestring | nullnullStarting shortcut when uncontrolled.
onValueChange(value: string | null, details: { replaced?: ShortcutBinding }) => void–Called with the new shortcut; replaced is the binding it was taken from after Use anyway.
resetValuestring | null–What the reset button restores. Defaults to defaultValue.
bindingsShortcutBinding[][]Shortcuts already in use: { shortcut, label }. Recording one asks before taking it.
warnReservedbooleantrueAlso warn about combinations the browser or system keeps, such as ⌘W and ⌘C.
requireModifierbooleantrueRequire ⌘, Ctrl, or ⌥. Function keys are always allowed.
platform"mac" | "other"–Overrides the detected platform.
placeholderstring"Record shortcut"Shown when there is no shortcut.
descriptionstring–Hint under the field.
disabledbooleanfalseDisables recording.
idstring–Id of the recorder button.
classNamestring–Class on the root.

ShortcutList

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

PropTypeDefaultDescription
groups (required)ShortcutListGroup[]–Groups: { label, items: { label, shortcut, keywords? }[] }.
labelstring"Keyboard shortcuts"Accessible name of the list.
searchablebooleantrueShows the search field.
searchPlaceholderstring"Search shortcuts"Search placeholder and label.
highlightPressedbooleantrueLight caps as keys are held and fade rows that do not use the held modifiers.
platform"mac" | "other"–Overrides the detected platform.
classNamestring–Class on the root.

ShortcutKeys

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

PropTypeDefaultDescription
shortcut (required)string–Such as "mod+k".
platform"mac" | "other"–Overrides the detected platform.
pressedReadonlySet<string>–Held key ids from usePressedKeys; matching caps light up.
size"sm" | "md""md"Cap size.
classNamestring–Class on the wrapper.

ShortcutKbd

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

PropTypeDefaultDescription
children (required)ReactNode–The key label.
pressedbooleanfalseDraws the key pushed down and lit.
size"sm" | "md""md"Cap size.
...propsHTMLAttributes<HTMLElement>–Forwarded to the kbd element.

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.

PropTypeDefaultDescription
event, shortcut, platform (required)KeyboardEvent, string, Platform–matchesShortcut returns true when the keydown is this shortcut.
shortcut, platform (required)string, Platform–formatShortcut returns { text, spoken }.
overridePlatform–usePlatform(override?) returns "mac" or "other"; the server assumes mac.
enabledbooleantrueusePressedKeys(enabled?) returns the set of held key ids.

Keyboard interactions

KeysAction
Enter / SpaceStarts recording.
Any combination (while recording)Records it; held modifiers show as caps as you build the chord.
Escape (while recording)Cancels recording.
Backspace / DeleteClears the shortcut, while recording or while the field has focus.
Tab (while recording)Stops recording and moves on without recording Tab.
Escape (in list search)Clears the ShortcutList search.

Accessibility

Motion

Responsive behavior

Performance

Notes for AI

Also in special inputs

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://ui.xzero.co.uk/llms.txt

Browse all components