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.
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.
- keysrequiredMaybeRef<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.
- callbackrequired(e: KeyboardEvent) => void
- Function called when the key combination or sequence is matched. Receives the native KeyboardEvent.
- optionsIHotkeyOptions{}
- Optional configuration: event type (default "keydown"), inputs flag, preventDefault flag, and sequenceTimeout (ms).
- options.eventstring'keydown'
- DOM keyboard event type to listen to.
- options.inputsbooleanfalse
- When false (default), the hotkey is suppressed while an input, textarea, or contenteditable element is focused.
- options.preventDefaultbooleantrue
- Calls event.preventDefault() when the hotkey matches.
- options.sequenceTimeoutnumber1000
- 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
Key sequence (vim-style)
Reactive hotkey (toggleable)