useHotkey

Call Signature#

function useHotkey<T>(
   hotkey, 
   callback, 
   options?): void;

Defined in: useHotkey.ts:86

React hook for registering a hotkey: a chord such as 'Mod+S', a sequence such as ['G', 'G'], or an app hotkey from defineAppHotkeys.

Uses the singleton HotkeyManager for efficient event handling. The callback and options sync on every render, so callbacks that reference React state always see the latest values. enabled: false keeps the registration (visible in devtools) and only suppresses firing.

Chords accept requireReset; sequences accept timeout. A one-step sequence registers as its chord. An app hotkey uses its effective hotkey from HotkeysProvider (including the user's custom hotkey) and its declared meta and options, and registers nothing while unbound.

Options merge in this order: provider defaults, app hotkey declaration, call-site options.

Type Parameters#

T#

T extends AppHotkey<string, HotkeyChord | HotkeySequence | null>

Parameters#

hotkey#

T

A chord string, RawHotkeyChord object, sequence, or app hotkey

callback#

HotkeyCallback

The function to call when the hotkey is pressed

options?#

UseAppHotkeyOptions<T>

Options for the hotkey behavior

Returns#

void

Examples#

function Editor() {
  const [count, setCount] = useState(0)

  useHotkey('Mod+S', () => save(count))
  useHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 })
  useHotkey('Escape', () => close(), { enabled: isOpen })
}

function Toolbar() {
  const appHotkeys = useAppHotkeys()
  useHotkey(appHotkeys['doc.save'], () => save())
}

Call Signature#

function useHotkey<T>(
   hotkey, 
   callback, 
   options?): void;

Defined in: useHotkey.ts:91

React hook for registering a hotkey: a chord such as 'Mod+S', a sequence such as ['G', 'G'], or an app hotkey from defineAppHotkeys.

Uses the singleton HotkeyManager for efficient event handling. The callback and options sync on every render, so callbacks that reference React state always see the latest values. enabled: false keeps the registration (visible in devtools) and only suppresses firing.

Chords accept requireReset; sequences accept timeout. A one-step sequence registers as its chord. An app hotkey uses its effective hotkey from HotkeysProvider (including the user's custom hotkey) and its declared meta and options, and registers nothing while unbound.

Options merge in this order: provider defaults, app hotkey declaration, call-site options.

Type Parameters#

T#

T extends RegisterableHotkey

Parameters#

hotkey#

T

A chord string, RawHotkeyChord object, sequence, or app hotkey

callback#

HotkeyCallback<HotkeyCallbackContextFor<T>>

The function to call when the hotkey is pressed

options?#

AdapterOptionsFor<T, UseHotkeyTarget>

Options for the hotkey behavior

Returns#

void

Examples#

function Editor() {
  const [count, setCount] = useState(0)

  useHotkey('Mod+S', () => save(count))
  useHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 })
  useHotkey('Escape', () => close(), { enabled: isOpen })
}

function Toolbar() {
  const appHotkeys = useAppHotkeys()
  useHotkey(appHotkeys['doc.save'], () => save())
}