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

Signature TypeScript complète extraite du fichier du composable.

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.

Interfaces consommées

IHotkeyOptions

API

Paramètres

Paramètres d'entrée acceptés par ce composable.

keys
requis
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
requis
(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

Valeurs de retour

Propriétés et méthodes exposées par l'objet retourné par le composable.

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

Exemples

Extraits de code prêts à coller.

Simple modifier hotkey

ts

Key sequence (vim-style)

ts

Reactive hotkey (toggleable)

ts