Skip to main content

​
Overview

Hotkey listener composable with key combination and sequence support. Platform-aware with automatic cleanup.

​
Features

  • Key combination support (ctrl+k, shift+enter)
  • Key sequence support (g-h for GitHub-style shortcuts)
  • Platform-aware modifiers (Mac: cmd→meta, others: cmd→ctrl)
  • Input focus detection (skip when typing in inputs)
  • Sequence timeout with automatic reset
  • Key alias normalization
  • Pause/resume/stop functionality
  • Automatic cleanup on scope disposal
  • SSR-safe (no-op when not in browser)

​
Function Signature

function useHotkey(
  keys: MaybeRefOrGetter<string | undefined>,
  callback: (e: KeyboardEvent) => void,
  options?: UseHotkeyOptions
): UseHotkeyReturn

​
Parameters

​
keys
MaybeRefOrGetter<string | undefined>
The hotkey string (e.g., ‘ctrl+k’, ‘g-h’). Can be reactive.
​
callback
(e: KeyboardEvent) => void
The function to call when the hotkey is triggered.
​
options
UseHotkeyOptions
​
event
'keydown' | 'keyup'
default:"'keydown'"
The keyboard event type to listen for.
​
inputs
boolean
default:"false"
Whether to trigger the callback when an input element is focused.
​
preventDefault
boolean
default:"true"
Whether to prevent the default browser action.
​
stopPropagation
boolean
default:"false"
Whether to stop event propagation.
​
sequenceTimeout
number
default:"1000"
Timeout in ms before a key sequence resets.

​
Return Value

​
isActive
Readonly<Ref<boolean>>
Whether the hotkey listener is currently active.
​
isPaused
Readonly<Ref<boolean>>
Whether the hotkey listener is currently paused.
​
pause
() => void
Pause listening (removes listener but keeps configuration).
​
resume
() => void
Resume listening after pause.
​
stop
() => void
Stop listening and clean up.

​
Examples

​
Simple combination

import { useHotkey } from '@vuetify/v0'

const { isActive, pause, resume } = useHotkey('ctrl+k', () => {
  console.log('Command palette opened')
})

​
Key sequence (GitHub-style)

useHotkey('g-h', () => {
  console.log('Go home')
})

​
With options

useHotkey('escape', closeModal, { 
  inputs: true,
  preventDefault: true 
})

​
Pause/resume control

const { pause, resume, isPaused } = useHotkey('ctrl+s', saveDocument)

// Temporarily disable
pause()
console.log(isPaused.value) // true

// Re-enable
resume()
console.log(isPaused.value) // false

​
Reactive hotkey

const currentHotkey = ref('ctrl+k')

useHotkey(currentHotkey, () => {
  console.log('Hotkey triggered')
})

// Change hotkey dynamically
currentHotkey.value = 'ctrl+p'

​
Multiple modifiers

useHotkey('ctrl+shift+k', () => {
  console.log('Complex combo')
})

​
Arrow key sequences

useHotkey('up-down', () => {
  console.log('Konami code part 1')
})

​
Platform-aware shortcuts

// On Mac: cmd+k, on Windows/Linux: ctrl+k
useHotkey('cmd+k', openCommandPalette)

​
Supported Key Aliases

​
Modifiers

  • ctrl / control
  • shift
  • alt / option
  • meta / cmd / command

​
Arrow Keys

  • up → ArrowUp
  • down → ArrowDown
  • left → ArrowLeft
  • right → ArrowRight

​
Common Keys

  • esc → Escape
  • space →
  • return → Enter
  • del → Delete

​
Key Combinations

Use + to combine keys: 
'ctrl+k'        // Ctrl + K
'shift+enter'   // Shift + Enter
'ctrl+shift+k'  // Ctrl + Shift + K

​
Key Sequences

Use - to create sequences: 
'g-h'           // Press G, then H
'g-i-t'         // Press G, then I, then T
'ctrl+k-p'      // Press Ctrl+K, then P

​
Input Focus Detection

By default, hotkeys are ignored when text inputs are focused:
  • <input type="text">, <input type="email">, etc.
  • <textarea>
  • Elements with contentEditable
  • Elements with ARIA roles: textbox, searchbox, combobox, spinbutton
Set inputs: true to override this behavior.

​
Notes

  • Platform-aware: cmd maps to meta on Mac, ctrl elsewhere
  • Sequences reset after sequenceTimeout milliseconds
  • Input detection helps prevent conflicts with form fields
  • SSR-safe: returns valid API structure with no-op listeners

Build docs developers (and LLMs) love

Get started for freeTalk to us