Record Custom Hotkeys with useHotkeyRecorder in Vue

useHotkeyRecorder lets users choose a hotkey by pressing it, as shortcut editors in system settings and IDEs do. You only need it if users can change your app's hotkeys. To save their choices and list them in a cheat sheet, pair it with app hotkeys.

While any recorder is listening, registered hotkeys don't fire, so pressing Mod+S to record it doesn't also save. You don't need to disable them yourself.

Record a chord#

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

const { isRecording, recordedHotkey, startRecording, cancelRecording } =
  useHotkeyRecorder({
    onRecord: (hotkey) => console.log('Recorded:', hotkey), // e.g. 'Mod+Shift+[KeyS]'
  })
</script>

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

The recorder records the key's position by default, so Option+S on macOS records Alt+[KeyS], even though it types ß. It records Mod rather than Command or Control, so the hotkey works on every platform. Pass the result straight to useHotkey, and label it with formatForDisplay. Recording captures what the user pressed explains these defaults. Set recordBy: 'key' to record the character instead.

The composable returns the recorder's state and controls. State members are readonly refs, so destructure them at the top level of <script setup> for templates to unwrap them, or read .value:

Record a sequence#

Set maxSteps: Infinity to let users record a sequence. Each chord adds a step, and the recording commits when the user presses Enter, or after idleTimeoutMs without a new step:

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

const { isRecording, steps, recordedHotkey, startRecording } = useHotkeyRecorder({
  maxSteps: Infinity,
  onRecord: (hotkey) => console.log('Recorded:', hotkey), // 'Mod+[KeyS]' or ['[KeyG]', '[KeyG]']
})
</script>

<template>
  <button @click="startRecording">
    {{
      isRecording
        ? formatForDisplay(steps) || 'Press chords, then Enter...'
        : recordedHotkey
          ? formatForDisplay(recordedHotkey)
          : 'Click to record'
    }}
  </button>
</template>

A one-step recording commits as a chord, so the result can always go straight to useHotkey. With maxSteps: Infinity, onRecord and validate receive a Hotkey, which can be a chord or a sequence. See Sequences for how sequences match.

Options can also be a ref or getter, such as useHotkeyRecorder(() => ({ maxSteps: Infinity, recordBy: mode.value, onRecord })), so the recorder follows reactive state.

Keys the recorder handles#

Repeats and IME composition never add a step. onClear doesn't change anything on its own, so your app decides whether clearing removes a hotkey or restores its default.

By default, the recorder ignores typing in text fields, so other fields on the page keep working while it listens. Escape still cancels. Set ignoreInputs: false to record from inside a text field.

Validate and check conflicts#

Reject hotkeys you don't want#

Pass validate to accept or reject each recording before it commits. Return true to accept, or false or a message to reject:

useHotkeyRecorder({
  validate: (_hotkey, { parsedChord }) =>
    parsedChord.modifiers.length > 0 || 'Include a modifier.',
  onReject: ({ message }) => setError(message),
  onRecord: (hotkey) => saveHotkey(hotkey),
})

The second argument has the event that recorded the chord and parsedChord, with Mod resolved. With maxSteps: Infinity, a recording can be a chord or a sequence, so check kind first. A sequence's context has events and parsedSequence, with one entry per step:

useHotkeyRecorder({
  maxSteps: Infinity,
  validate: (_hotkey, context) =>
    context.kind === 'sequence' ||
    context.parsedChord.modifiers.length > 0 ||
    'A single chord needs a modifier.',
  onRecord: (hotkey) => saveHotkey(hotkey),
})

A rejected recording keeps listening, so the user can try again. A rejected sequence recording keeps its steps, so the user can edit them with Backspace.

Check for conflicts#

Set detectConflicts: true to reject a hotkey that's already registered:

useHotkeyRecorder({
  detectConflicts: true,
  onReject: ({ reason, message, conflicts }) => {
    // reason is 'conflict', and conflicts lists the registrations it collides with
    setError(message)
  },
  onRecord: (hotkey) => saveHotkey(hotkey),
})

By default, the check compares the recording with every enabled keydown hotkey on the page, in every scope. A recorded chord conflicts with a sequence that starts with it, and a recorded sequence conflicts with a chord equal to its first step. Pass an object instead of true to change what's checked:

detectConflicts: {
  excludeIds: [registration.id], // Skip the hotkey being changed
  target: panelElement, // Only hotkeys on this element, inside it, or around it
  scope: 'all', // Ignore target and check hotkeys on every element. Unrelated to hotkey scopes.
  eventType: 'keyup', // Check keyup hotkeys instead
  includeDisabled: true, // Include disabled hotkeys
  exclude: (registration) => registration.options.scope === 'vim', // Skip one hotkey scope
}

A conflict check finds hotkeys that could collide. It can't promise which callback a key press would run, because propagation, typing in fields, other listeners, and pages that haven't rendered all affect that. To check app hotkeys, including ones on pages that haven't rendered, use findConflicts from app hotkeys instead.

onReject receives a reason: 'conflict', 'validation', 'invalid', 'missing-code' for a key press with no physical code, or 'alt-graph' for AltGr typing a character. It also receives a message, the rejected hotkey when there is one, and the conflicts for a conflict.

To check a hotkey outside a recording, call findHotkeyConflicts(hotkey, options). It takes the same options, and returns registration views.

Build a shortcut settings screen#

For an app-wide settings screen, declare your hotkeys as app hotkeys, and save each recording with setCustomHotkey. That keeps cheat sheets, conflict checks, and saved choices in one place. Change hotkeys shows a settings row built that way.

For a few hotkeys in one component, refs are enough:

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

const actions = { save, undo, search }
type Action = keyof typeof actions

const shortcuts = ref<Record<Action, Hotkey>>({
  save: 'Mod+S',
  undo: 'Mod+Z',
  search: ['G', 'S'],
})
const editing = ref<Action | null>(null)

const { isRecording, startRecording } = useHotkeyRecorder({
  maxSteps: Infinity,
  onRecord: (hotkey) => {
    if (editing.value) shortcuts.value = { ...shortcuts.value, [editing.value]: hotkey }
    editing.value = null
  },
  onCancel: () => (editing.value = null),
})

// Register each action with its current hotkey
useHotkeys(() =>
  Object.entries(shortcuts.value).map(([action, hotkey]) => ({
    hotkey,
    callback: actions[action as Action],
  })),
)

function edit(action: Action) {
  editing.value = action
  startRecording()
}
</script>

<template>
  <div>
    <button v-for="(hotkey, action) in shortcuts" :key="action" @click="edit(action)">
      {{ action }}:
      {{ editing === action && isRecording ? 'Press keys...' : formatForDisplay(hotkey) }}
    </button>
  </div>
</template>

Recorder options#

To change the defaults for every recorder, pass hotkeyRecorder options to HotkeysProvider. See Set default options. The useHotkeyRecorder reference lists the types.

The useHotkeyRecorder example records chords, and the sequences example records sequences.