useHotkey
A composable for handling hotkey combinations and sequences with platform-aware modifiers and automatic cleanup.
Usage
The useHotkey composable registers hotkey handlers on the window with automatic cleanup when the component is unmounted. It supports key combinations (ctrl+k), key sequences (g-h), and platform-aware modifier mapping.
<script setup lang="ts">
import { useHotkey } from '@vuetify/v0'
import { ref } from 'vue'
const commandPaletteOpen = ref(false)
const message = ref('')
// Simple key combination - Ctrl+K (Cmd+K on Mac)
useHotkey('ctrl+k', () => {
commandPaletteOpen.value = true
})
// Key sequence (GitHub-style) - press 'g' then 'h'
useHotkey('g-h', () => {
message.value = 'Go home!'
})
// With multiple modifiers
useHotkey('ctrl+shift+s', () => {
message.value = 'Save all!'
})
// Allow in inputs with the inputs option
useHotkey('escape', () => {
commandPaletteOpen.value = false
}, { inputs: true })
</script>
<template>
<div>
<p>Press Ctrl+K to open command palette</p>
<p>Press g then h for GitHub-style navigation</p>
<p v-if="message">{{ message }}</p>
</div>
</template>Key Aliases
Key strings are normalized before matching, so you can use human-friendly names instead of exact KeyboardEvent.key values:
| Alias | Canonical |
|---|---|
esc | escape |
return | enter |
del | delete |
space, spacebar | |
up / down / left / right | arrowup / arrowdown / arrowleft / arrowright |
control | ctrl |
command | cmd |
option | alt |
plus | + |
minus, hyphen | - |
slash | / |
underscore | _ |
// These are equivalent:
useHotkey('escape', close)
useHotkey('esc', close)
useHotkey('ctrl+plus', zoomIn) // matches Ctrl ++
useHotkey('cmd+minus', zoomOut) // matches Cmd +-Architecture
useHotkey builds on useEventListener for keyboard event handling:
Reactivity
| Property/Method | Reactive | Notes |
|---|---|---|
isActive | Computed from cleanup ref | |
isPaused | ShallowRef, readonly | |
keys | Accepts MaybeRefOrGetter, watched for changes |
Examples
Command Palette
A searchable command palette (Cmd+J) with arrow-key navigation, filtered results, and per-command shortcuts.
Functions
useHotkey
(keys: MaybeRefOrGetter<string | undefined>, callback: (e: KeyboardEvent) => void, options?: UseHotkeyOptions, _platform?: PlatformContext | undefined) => UseHotkeyReturnA composable that listens for hotkey combinations and sequences.
Options
event
MaybeRefOrGetter<"keydown" | "keyup"> | undefinedThe keyboard event type to listen for.
Default: 'keydown'
inputs
MaybeRefOrGetter<boolean> | undefinedWhether to trigger the callback when an input element is focused.
Default: false
preventDefault
MaybeRefOrGetter<boolean> | undefinedWhether to prevent the default browser action.
Default: true
stopPropagation
MaybeRefOrGetter<boolean> | undefinedWhether to stop event propagation.
Default: false
sequenceTimeout
MaybeRefOrGetter<number> | undefinedTimeout in ms before a key sequence resets.
Default: 1000
Properties
isActive
Readonly<Ref<boolean, boolean>>Whether the hotkey listener is currently active (listening for keys). False when paused, when keys is undefined, or in SSR.