HotkeyManager

Singleton manager for hotkey registrations, including sequences.

This class provides a centralized way to register and manage keyboard hotkeys. It attaches one keydown and one keyup listener per target, regardless of how many hotkeys are registered.

Sequences (Vim-style hotkeys such as ['G', 'G']) match when every step is pressed within the timeout. Modifier-only events (Shift, Control, Alt, or Meta alone) neither advance nor reset a sequence, so chained modifier chords such as ['Shift+R', 'Shift+T'] work.

Example

const manager = HotkeyManager.getInstance()

const save = manager.register('Mod+S', (event, context) => {
  console.log('Save triggered!')
})
const top = manager.register(['G', 'G'], () => scrollToTop(), { timeout: 500 })

// Later, to unregister:
save.unregister()
top.unregister()

Properties

appHotkeys

readonly appHotkeys: Store<
  | AppHotkeysStore<Readonly<Record<string, AppHotkey<string, 
  | HotkeyChord
  | HotkeySequence
  | null>>>>
| null>;

Defined in: hotkey-manager.ts:340

The app hotkeys store published by a framework provider, so tools such as devtools can list declared hotkeys that are not registered.

registrations

readonly registrations: Store<Map<string, HotkeyRegistration>>;

Defined in: hotkey-manager.ts:333

The TanStack Store containing all hotkey registrations, chords and sequences. Use this to subscribe to registration changes or access current registrations.

Example

const manager = HotkeyManager.getInstance()

// Subscribe to registration changes
const unsubscribe = manager.registrations.subscribe(() => {
  console.log('Registrations changed:', manager.registrations.state.size)
})

// Access current registrations
for (const [id, reg] of manager.registrations.state) {
  console.log(reg.hotkey, reg.options.enabled)
}

Methods

destroy()

destroy(): void;

Defined in: hotkey-manager.ts:1042

Destroys the manager and removes all listeners.

Returns

void

getRegistrationCount()

getRegistrationCount(): number;

Defined in: hotkey-manager.ts:1012

Gets the number of registered hotkeys, chords and sequences.

Returns

number

isRegistered()

isRegistered(hotkey, target?): boolean;

Defined in: hotkey-manager.ts:1023

Checks if a specific hotkey is registered.

Parameters

hotkey

RegisterableHotkey

The chord or sequence to check

target?

Target

Optional target element to match (if provided, both hotkey and target must match)

Returns

boolean

True if a matching registration exists

register()

register<T>(
   hotkey, 
   callback, 
options?): HotkeyRegistrationHandle<HotkeyOptionsFor<T>>;

Defined in: hotkey-manager.ts:410

Registers a hotkey handler and returns a handle for updating the registration.

Pass a chord ('Mod+S' or a RawHotkey object) or a sequence (['G', 'G']). A one-step sequence registers as its chord. Chords accept requireReset; sequences accept timeout.

The returned handle allows updating the callback and options without re-registering, which is useful for avoiding stale closures in React.

Type Parameters

T

T extends RegisterableHotkey

Parameters

hotkey

A chord string, RawHotkey object, or sequence

callback

HotkeyCallback

The function to call when the hotkey is pressed

options?

HotkeyOptionsFor<T>

Options for the hotkey behavior

Returns

HotkeyRegistrationHandle<HotkeyOptionsFor<T>>

A handle for managing the registration

Example

const handle = manager.register('Mod+S', callback)

// Update callback without re-registering (avoids stale closures)
handle.callback = newCallback

// Update options
handle.setOptions({ enabled: false })

// Unregister when done
handle.unregister()

resetSequenceProgress()

resetSequenceProgress(): void;

Defined in: hotkey-manager.ts:957

Resets the progress of every in-progress sequence.

Returns

void

triggerRegistration()

triggerRegistration(id): boolean;

Defined in: hotkey-manager.ts:975

Triggers a registration's callback programmatically from devtools. Creates a synthetic KeyboardEvent from the chord (or a sequence's last step) and invokes the callback.