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.
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.
- keysrequisMaybeRef<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.
- callbackrequis(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
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
Key sequence (vim-style)
Reactive hotkey (toggleable)