Hotkey Recording Guide

TanStack Hotkeys provides the useHotkeyRecorder composable for building shortcut customization UIs in Vue.

Basic Usage

vue

<script setup lang="ts">
import { formatForDisplay, useHotkeyRecorder } from '@tanstack/vue-hotkeys'

const recorder = useHotkeyRecorder({
  onRecord: (hotkey) => {
    console.log('Recorded:', hotkey)
  },
})
</script>

<template>
  <div>
    <button @click="recorder.isRecording ? recorder.stopRecording() : recorder.startRecording()">
      {{
        recorder.isRecording
          ? 'Press a key combination...'
          : recorder.recordedHotkey
            ? formatForDisplay(recorder.recordedHotkey)
            : 'Click to record'
      }}
    </button>
    <button v-if="recorder.isRecording" @click="recorder.cancelRecording()">
      Cancel
    </button>
  </div>
</template>

Return Value

isRecording: reactive ref-like value indicating whether recording is active
recordedHotkey: reactive ref-like value with the most recently recorded hotkey
startRecording(): start listening for key presses
stopRecording(): stop listening and keep the current recording
cancelRecording(): stop listening and discard the in-progress recording

Options

useHotkeyRecorder({
  onRecord: (hotkey) => {},
  onCancel: () => {},
  onClear: () => {},
})

Global Default Options via Provider

vue

<script setup lang="ts">
import { HotkeysProvider } from '@tanstack/vue-hotkeys'
</script>

<template>
  <HotkeysProvider
    :default-options="{
      hotkeyRecorder: {
        onCancel: () => console.log('Recording cancelled'),
      },
    }"
  >
    <AppContent />
  </HotkeysProvider>
</template>

ignoreInputs

The HotkeyRecorderOptions supports an ignoreInputs option (defaults to true). When true, the recorder will not intercept normal typing in text inputs, textareas, selects, or contentEditable elements -- keystrokes pass through to the input as usual. Pressing Escape still cancels recording even when focused on an input. Set ignoreInputs: false if you want the recorder to capture keys from within input elements.

useHotkeyRecorder({
  ignoreInputs: false, // record even from inside inputs
  onRecord: (hotkey) => console.log(hotkey),
})

Recording Behavior

Modifier-only presses do not complete a recording.
Modifier plus key combinations record the full shortcut.
Escape cancels recording.
Backspace and Delete clear the shortcut.
Recorded values are normalized to portable Mod format.

Basic Usage#

Return Value#

Options#

Global Default Options via Provider#