Record Custom Hotkeys with createHotkeyRecorder in Svelte

createHotkeyRecorder 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 lang="ts">
  import { createHotkeyRecorder, formatForDisplay } from '@tanstack/svelte-hotkeys'

  const recorder = createHotkeyRecorder({
    onRecord: (hotkey) => console.log('Recorded:', hotkey), // e.g. 'Mod+Shift+[KeyS]'
  })
</script>

<div>
  <button onclick={recorder.startRecording}>
    {recorder.isRecording
      ? 'Press a key combination...'
      : recorder.recordedHotkey
        ? formatForDisplay(recorder.recordedHotkey)
        : 'Click to record'}
  </button>
  {#if recorder.isRecording}
    <button onclick={recorder.cancelRecording}>Cancel</button>
  {/if}
</div>

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 createHotkey, and label it with formatForDisplay. Recording captures what the user pressed explains these defaults. Set recordBy: 'key' to record the character instead.

createHotkeyRecorder returns the recorder's state and controls. State members are reactive getters, so read them from the recorder object instead of destructuring them once:

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 lang="ts">
  import { createHotkeyRecorder, formatForDisplay } from '@tanstack/svelte-hotkeys'

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

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

A one-step recording commits as a chord, so the result can always go straight to createHotkey. 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 getter, such as createHotkeyRecorder(() => ({ maxSteps: Infinity, recordBy: mode, onRecord })), so the recorder follows $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:

createHotkeyRecorder({
  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:

createHotkeyRecorder({
  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:

createHotkeyRecorder({
  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, $state is enough:

<script lang="ts">
  import {
    createHotkeyRecorder,
    createHotkeys,
    formatForDisplay,
  } from '@tanstack/svelte-hotkeys'
  import type { Hotkey } from '@tanstack/svelte-hotkeys'

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

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

  const recorder = createHotkeyRecorder({
    maxSteps: Infinity,
    onRecord: (hotkey) => {
      if (editing) shortcuts = { ...shortcuts, [editing]: hotkey }
      editing = null
    },
    onCancel: () => (editing = null),
  })

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

<div>
  {#each Object.entries(shortcuts) as [action, hotkey] (action)}
    <button
      onclick={() => {
        editing = action as Action
        recorder.startRecording()
      }}
    >
      {action}:
      {editing === action && recorder.isRecording ? 'Press keys...' : formatForDisplay(hotkey)}
    </button>
  {/each}
</div>

Recorder options#

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

The create-hotkey-recorder example records chords, and the sequences example records sequences.