HotkeyField

When to useLink to "When to use"

• Shortcut settings: each action on a keybindings page gets a HotkeyField, with recording controlled so one row records at a time.

Use something else when: you only show a shortcut (Kbd), or people type a key name as text (TextField).

UsageLink to "Usage"

import { HotkeyField, useHotkey } from "@arshad-shah/cynosure";

const [keys, setKeys] = useState("mod+shift+p");
useHotkey(keys, openPalette);

<HotkeyField label="Command palette" value={keys} onChange={setKeys} name="palette" />

One row at a timeLink to "One row at a time"

Control recording from the page, so starting one row ends the other. Starting it from outside (an Edit button) moves focus into the field so the keys reach it.

<HotkeyField
  label={binding.label}
  labelHidden
  value={binding.keys}
  onChange={(keys) => save(binding.id, keys)}
  recording={editing === binding.id}
  onRecordingChange={(on) => setEditing(on ? binding.id : null)}
/>

Plain keysLink to "Plain keys"

By default a shortcut needs Control, Command or Alt, since a plain letter types in text fields (useHotkey ignores plain keys there). Function keys always count. allowBare accepts plain keys ("k", "shift+/") for shortcuts that only work outside text fields.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Capture: keys are taken in the capture phase on the field's own element, with propagation stopped and the default prevented, so neither useHotkey nor any document listener sees them. It works inside shadow roots.
• Key names: the key is the character typed or, when that is not a letter or digit (Option+K types "˚" on macOS, Shift+1 types "!", a dead key, another alphabet), the letter or digit on the physical key, as matchesHotkey reads it. mod is Command on Apple platforms and Control elsewhere, so a recorded shortcut works on both. The mapping is exported as hotkeyFromEvent.
• Names: the label names the group (a fieldset); the record toggle is a pressed/not-pressed button described by the shortcut, so it is read as "Record shortcut, Control plus Shift plus P".
• Announcements: the field's own role="status" says "Recording, press a shortcut", then "Shortcut set to …", "Recording cancelled" or "Shortcut cleared" (labels), through a LiveRegion, so the same message twice (cancelling twice) is spoken twice.
• Focus: clearing moves focus to the record toggle, since the clear button goes with the shortcut. Focus leaving the field while recording cancels it.
• Forms: with name, the form receives the shortcut string; a reset restores defaultValue; a disabled field is not submitted.
• Reduced motion: the recording light stops pulsing and stays lit.

TouchLink to "Touch"

The buttons keep a 44px hit area on coarse pointers. On a touch-only device there is usually no keyboard to record with; the field still shows and clears shortcuts.

ThemingLink to "Theming"

The box shares TextField's skin through Field's --cy-field-control-* tokens, so restyling those restyles both; a disabled box takes --cy-field-control-sunken-bg.

The key caps are Kbd and the buttons IconButton: restyle them through their tokens.

RelatedLink to "Related"

Kbd · CommandPalette · Field