useHotkey

Commons
stable

Registers a global keyboard shortcut (single key, modifier combination, or multi-step sequence) and calls the provided callback on match. Automatically cleans up the event listener on component unmount. Supports reactive key strings via MaybeRef.

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

useHotkey is a no-op in SSR (non-browser environments). On macOS, "cmd" and "meta" map to the Command key; "ctrl+cmd" is treated as Ctrl+Meta to cover cross-platform combinations.

Consumed interfaces

IHotkeyOptions

API

Parameters

Input parameters accepted by this composable.

keys
required
MaybeRef<string | undefined>
Hotkey definition string. Use "+" to combine modifiers (e.g. "ctrl+k"), ">" to define a sequence (e.g. "g>i"). Accepted modifiers: ctrl, shift, alt, meta, cmd. Reactive — updating the ref re-registers the listener.
callback
required
(e: KeyboardEvent) => void
Function called when the key combination or sequence is matched. Receives the native KeyboardEvent.
options
IHotkeyOptions
{}
Optional configuration: event type (default "keydown"), inputs flag, preventDefault flag, and sequenceTimeout (ms).
options.event
string
'keydown'
DOM keyboard event type to listen to.
options.inputs
boolean
false
When false (default), the hotkey is suppressed while an input, textarea, or contenteditable element is focused.
options.preventDefault
boolean
true
Calls event.preventDefault() when the hotkey matches.
options.sequenceTimeout
number
1000
Time in milliseconds between consecutive keys in a sequence before it resets.

API

Return values

Properties and methods exposed by the composable return object.

cleanup
Function that removes the event listener and clears any pending sequence timer. Called automatically on unmount when useHotkey is used inside a component setup.

Usage

Examples

Ready-to-paste usage snippets.

Simple modifier hotkey

ts

Key sequence (vim-style)

ts

Reactive hotkey (toggleable)

ts