HotkeyRecorder

Defined in: hotkey-recorder.ts:179

Framework-agnostic class for recording keyboard shortcuts.

With the default maxSteps: 1, the first valid chord commits. With a larger maxSteps, each chord adds a step; the recording commits on Enter (unless commitKeys: 'none'), after idleTimeoutMs, or when it reaches maxSteps. Backspace/Delete removes the last step, and on an empty recording calls onClear. Escape cancels. A one-step result is a chord string.

State Management:

• Uses TanStack Store for reactive state management
• State can be accessed via recorder.store.state when using the class directly
• When using framework adapters, use the useHotkeyRecorder hook for reactive state

Example#

const recorder = new HotkeyRecorder({
  onRecord: (hotkey) => {
    console.log('Recorded:', hotkey) // 'Mod+S'
  },
})

const sequenceRecorder = new HotkeyRecorder({
  maxSteps: 3,
  onRecord: (hotkey) => {
    console.log('Recorded:', hotkey) // 'Mod+S' or ['G', 'H']
  },
})

recorder.start()
// ... later
recorder.destroy()

Constructors#

Constructor#

new HotkeyRecorder(options): HotkeyRecorder;

Defined in: hotkey-recorder.ts:204

Parameters#

options#

| HotkeyChordRecorderOptions | (() => HotkeyChordRecorderOptions)

Returns#

HotkeyRecorder

Constructor#

new HotkeyRecorder(options): HotkeyRecorder;

Defined in: hotkey-recorder.ts:207

Parameters#

options#

| HotkeySequenceRecorderOptions | (() => HotkeySequenceRecorderOptions)

Returns#

HotkeyRecorder

Properties#

store#

readonly store: Store<HotkeyRecorderState>;

Defined in: hotkey-recorder.ts:180

Methods#

cancel()#

cancel(): void;

Defined in: hotkey-recorder.ts:453

Cancel recording without saving.

Removes the event listener, resets the recording state, and calls the onCancel callback if provided.

Returns#

void

commit()#

commit(): void;

Defined in: hotkey-recorder.ts:362

Commits the recorded steps after validation and conflict checks. Called automatically at maxSteps, on Enter, or after idleTimeoutMs. A rejected commit leaves recording active with its steps intact.

Returns#

void

destroy()#

destroy(): void;

Defined in: hotkey-recorder.ts:480

Clean up event listeners and reset state.

Call this when you're done with the recorder to ensure all event listeners are properly removed.

Returns#

void

setOptions()#

setOptions(options): void;

Defined in: hotkey-recorder.ts:220

Updates the recorder options, including callbacks. This allows framework adapters to sync callback changes without recreating the recorder.

Parameters#

options#

Partial<HotkeyRecorderOptions>

Returns#

void

start()#

start(): void;

Defined in: hotkey-recorder.ts:254

Start recording a new hotkey.

Sets up a keydown event listener that captures keyboard events and records chords according to maxSteps.

Returns#

void

stop()#

stop(): void;

Defined in: hotkey-recorder.ts:443

Stop recording (same as cancel, but doesn't call onCancel).

Removes the event listener and resets the recording state.

Returns#

void