Hotkeys

Provides a simple and powerful way to register keyboard shortcuts that work across different platforms and input contexts.

Copy Page as Markdown

ads via vuetify

Quick start

To get started, import the useHotkey composable:

<script setup>
  import { useHotkey } from 'vuetify'

  useHotkey('ctrl+s', () => {
    console.log('Save action')
  })
</script>

Usage

The hotkey composable takes a key combination string and a callback function. It automatically handles platform differences, key sequences, and provides options for customizing behavior.

Activity log

Hotkey command

No Events

Current hotkey:

<span>Current hotkey:</span>
<v-hotkey keys="cmd+b" />
<pre>log: {{ log }}</pre>

<script setup>
  import { shallowRef } from 'vue'
  import { useHotkey } from 'vuetify'

  const log = shallowRef('')

  function onHotkey () {
    log.value += '\n- Hotkey pressed'
  }

  useHotkey('cmd+b', onHotkey, {
  sequenceTimeout: 2000,
})
</script>

API

Composable	Description
useHotkey	The useHotkey composable

Guide

The useHotkey composable provides a declarative way to handle keyboard shortcuts in your Vue applications. It automatically cleans up event listeners when components are unmounted and supports reactive key combinations.

Basic hotkeys

Press the keyboard shortcuts below to trigger actions:

Hotkey	Action	Description
	Save Document	Cross-platform save shortcut
	Undo Action	Standard undo shortcut

Activity Log:

No hotkeys triggered yet...

Key sequences

Create multi-step keyboard shortcuts by separating keys with dashes. Users must press keys in sequence within the timeout period:

Key sequences require pressing keys in order within the timeout period. Try the sequences below:

Hotkey	Action	Description
	Command Palette	Press Ctrl+X, then P (within timeout)
	Go to Top	Press G, then G (Vim-style navigation)
	Save File	Press Ctrl+X, then Ctrl+S (Emacs-style)

Sequence Timeout

You have 2000ms to complete each sequence. If you wait too long, the sequence will reset.

Sequence Timeout (2000ms)

Activity Log:

No sequences triggered yet...

Platform awareness

The composable automatically handles platform differences. Use cmd for cross-platform compatibility or specific modifiers for platform-specific behavior:

Current Platform: Windows/Linux

The useHotkey composable automatically adapts to your platform.

Try the hotkeys below to see how they adapt to your platform:

Available Hotkeys

Hotkey	Action	Platform Behavior
	Copy	Ctrl on PC
	Paste	Ctrl on PC
	Redo	Ctrl+Shift on PC
	Select All (Explicit Ctrl)	Always Ctrl, even on Mac
	Find in Page	Ctrl key on PC

Activity Log:

No platform-aware hotkeys triggered yet...

Platform Detection Details

Property	Value
Platform Detected	Windows/Linux
User Agent	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36
cmd maps to	Control key (Ctrl)

Reactive hotkeys

Key combinations can be reactive, allowing you to change hotkeys dynamically:

Hotkey combinations can be reactive, allowing you to change them dynamically. Try changing the hotkey combinations below:

Save Hotkey

e.g., cmd+s, ctrl+shift+s

Undo Hotkey

e.g., cmd+z, ctrl+z

Custom Action Hotkey

e.g., alt+shift+x, f5

Enable hotkeys

Current Active Hotkeys

Hotkey	Action	Status
	Save Document	Active
	Undo Action	Active
	Custom Action	Active

Activity Log:

No reactive hotkeys triggered yet...

Options

Customize hotkey behavior with options for event type, input handling, and more:

Customize hotkey behavior with various options. Change the settings below and test the hotkeys:

Options Configuration

When to trigger the hotkey

Allow hotkeys in input fields

Prevent default browser behavior

Sequence Timeout (2000ms)

Test Hotkeys

Hotkey	Action	Settings
	Test Basic Hotkey	Event: keydown
	Test Sequence	Timeout: 2000ms
	Test in Input	Enabled in inputs

Test Input Field

Try pressing Enter or Cmd+J while focused here

Current Configuration

Option	Value	Description
`event`	keydown	When to trigger the hotkey callback
`inputs`	true	Allow hotkeys when input elements are focused
`preventDefault`	true	Prevent default browser behavior
`sequenceTimeout`	2000ms	Time limit for completing key sequences

Activity Log:

No hotkeys with options triggered yet...

Configuration options

The useHotkey composable accepts an optional third parameter of type HotkeyOptions to customize its behavior:

interface HotkeyOptions {
  event?: 'keydown' | 'keyup'
  inputs?: boolean
  preventDefault?: boolean
  sequenceTimeout?: number
}

Event type

Control which keyboard event triggers the hotkey:

// Trigger on key press (default)
useHotkey('ctrl+s', handleSave, { event: 'keydown' })

// Trigger on key release
useHotkey('ctrl+s', handleSave, { event: 'keyup' })

When to use:

keydown: For actions that should trigger immediately when pressed (most common)
keyup: For actions that should wait until the key is released, useful for preventing repeated triggers

Input handling

By default, hotkeys are disabled when input elements are focused to prevent conflicts with typing:

// Default: hotkeys disabled in input fields
useHotkey('ctrl+s', handleSave)

// Allow hotkeys even when inputs are focused
useHotkey('ctrl+s', handleSave, { inputs: true })

Best practices:

Keep inputs: false (default) for global shortcuts like save/copy/paste
Use inputs: true for application-specific shortcuts that should work everywhere
Consider using different key combinations for input-specific actions

Prevent default behavior

Control whether the browser’s default behavior for the key combination is prevented:

// Prevent browser default (recommended for most cases)
useHotkey('ctrl+s', handleSave, { preventDefault: true })

// Allow browser default behavior
useHotkey('f5', handleRefresh, { preventDefault: false })

When to disable:

When you want to enhance rather than replace browser behavior
For accessibility keys that should maintain their original function
When testing or debugging hotkey interactions

Sequence timeout

For key sequences, control how long users have between keystrokes:

// Default: 1 second between sequence steps
useHotkey('ctrl+k-p', openPalette)

// Faster timeout for expert users
useHotkey('ctrl+k-p', openPalette, { sequenceTimeout: 500 })

// Longer timeout for accessibility
useHotkey('ctrl+k-p', openPalette, { sequenceTimeout: 2000 })

Key combination syntax

The hotkey string supports various modifiers and special keys:

Modifiers

cmd / meta - Command key (Mac) / Control key (PC) - recommended over ctrl for cross-platform
ctrl - Control key (all platforms)
alt - Alt key (all platforms)
shift - Shift key (all platforms)

Special keys

enter, escape, tab, space, backspace, delete
arrowup, arrowdown, arrowleft, arrowright
home, end, pageup, pagedown
f1 through f12
plus, slash, underscore, and minus/hyphen for literal +, /, _, and -

Syntax rules

Parsing is performed left to right, so ctrl+s-a will produce “ctrl+s and then a”
Use + or _ to combine modifiers with keys: ctrl+s, ctrl_s
Use / to separate alternative keys or combinations: ctrl+k/ctrl+f, up/down
Use - to create sequences: ctrl+k-p (Ctrl+K, then P) ctrl+k/ctrl+f-p (Ctrl+K or Ctrl+F, then P)
Keys are case-insensitive: Ctrl+S equals ctrl+s

Check out all possible keycodes.

Manual cleanup

The composable automatically manages cleanup during the Vue component’s unmount lifecycle event. If you need to perform manual cleanup, you can save the cleanup function returned by the composable. Executing this function will remove the hotkey listener.

const cleanup = useHotkey('ctrl+s', () => {
  console.log('Save action')
})

// Later, manually cleanup
cleanup()

Avoiding key binding conflicts

Prevent conflicts by avoiding reserved shortcuts and organizing hotkeys systematically:

Common conflicts to avoid

// ❌ Browser shortcuts
useHotkey('f5', handleAction)        // Refresh
useHotkey('ctrl+t', handleAction)    // New tab
useHotkey('ctrl+w', handleAction)    // Close tab

// ❌ OS shortcuts
useHotkey('alt+tab', handleAction)   // Window switching

// ✅ Safe alternatives
useHotkey('cmd+shift+r', handleAction)
useHotkey('cmd+k-t', handleAction)
useHotkey('alt+1', handleAction)

Best practices

Hotkeys are a powerful feature, but they utilize APIs that are managed by the browser and the operating system. The reliability of the key bindings you make are subject to factors that can be difficult to control. It’s recommended you test your key bindings in the browsers and operating systems you are targeting.

Test cross-platform: Verify shortcuts work on Windows, macOS, and Linux!
Use modifier combinations: Prefer Ctrl+Shift+Key for custom actions
Document your shortcuts: Maintain a list of all application hotkeys in your application

Ready for more?

Continue your learning with related content selected by the Team or move between pages by using the navigation links below.

#Hotkeys

#Quick start

#Usage

#API

#Guide

#Basic hotkeys

Activity Log:

#Key sequences

Activity Log:

#Platform awareness

Available Hotkeys

Activity Log:

Platform Detection Details

#Reactive hotkeys

Current Active Hotkeys

Activity Log:

#Options

Options Configuration

Test Hotkeys

Current Configuration

Activity Log:

#Configuration options

#Event type

#Input handling

#Prevent default behavior

#Sequence timeout

#Key combination syntax

#Modifiers

#Special keys

#Syntax rules

#Manual cleanup

#Avoiding key binding conflicts

#Common conflicts to avoid

#Best practices

Ready for more?

Hotkeys

Quick start

Usage

API

Guide

Basic hotkeys

Key sequences

Platform awareness

Reactive hotkeys

Options

Configuration options

Event type

Input handling

Prevent default behavior

Sequence timeout

Key combination syntax

Modifiers

Special keys

Syntax rules

Manual cleanup

Avoiding key binding conflicts

Common conflicts to avoid

Best practices