HotkeyManager

Singleton manager for hotkey registrations, including sequences.

This class provides a centralized way to register and manage keyboard hotkeys. It shares one keydown and one keyup listener per target and capture phase across registrations.

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:373

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:366

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:1084

Destroys the manager and removes all listeners.

Returns

void

getRegistrationCount()

getRegistrationCount(): number;

Defined in: hotkey-manager.ts:1054

Gets the number of registered hotkeys, chords and sequences.

Returns

number

isRegistered()

isRegistered(hotkey, target?): boolean;

Defined in: hotkey-manager.ts:1065

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:437

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:1006

Resets the progress of every in-progress sequence.

Returns

void

triggerRegistration()

triggerRegistration(id): boolean;

Defined in: hotkey-manager.ts:1024

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.