# Tanstack Vue Hotkeys

> Use when adding or fixing keyboard shortcuts in a Vue 3 app with @tanstack/vue-hotkeys: useHotkey and useHotkeys composables, refs and getters as options, template-ref targets, HotkeysProvider and provideHotkeysContext scopes, app hotkey composables, recorders, held-key and hint composables, or replacing @keydown handlers and window keydown listeners.

- Skill: `lukasa1993/tanstack-vue-hotkeys` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add lukasa1993/tanstack-vue-hotkeys`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lukasa1993/tanstack-vue-hotkeys/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: lukasa1993 (https://skillmd.com/u/lukasa1993)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/lukasa1993/tanstack-vue-hotkeys

---


# TanStack Hotkeys in Vue

Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).

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

const isDirty = ref(false)
const panel = ref<HTMLDivElement | null>(null)

useHotkey('Mod+S', () => save(), { enabled: isDirty })
useHotkey('Escape', () => closePanel(), { target: panel })
</script>

<template>
  <div ref="panel" tabindex="0" @input="isDirty = true">
    Save <kbd>{{ formatForDisplay('Mod+S') }}</kbd>
  </div>
</template>
```

## API

| API                                       | What it's for                                                                                                                                                                                            |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey while the component is mounted; the hotkey and options can be refs or getters.                                                                               |
| `useHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a ref or getter of a list built from data, in one call.                                                                                                                     |
| `<HotkeysProvider>`                       | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for its children, and emit `custom-hotkeys-change`.                                                                   |
| `provideHotkeysContext(options)`          | Provide the same options from a component's setup instead of rendering `HotkeysProvider`; they apply to its children.                                                                                    |
| `useHotkeysContext()`                     | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider.                                                                                                             |
| `useDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                                                                                               |
| `useFormatForDisplay()`                   | Get `formatForDisplay` with the provider's `platform` filled in, for labels in server-rendered apps. Call it in `setup`.                                                                                 |
| `useAppHotkeys()`                         | Get a computed ref of the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
| `useAppHotkeyList()`                      | Get a computed ref listing every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                       |
| `useCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                                    |
| `useHotkeyRecorder(options)`              | Record a chord or sequence the user presses; destructure the refs it returns.                                                                                                                            |
| `useHotkeyRegistrations()`                | Get a ref listing every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope).                                                                          |
| `useHotkeyScopesState()`                  | Get a ref of the active scopes and the exclusive scope that owns the keyboard.                                                                                                                           |
| `useHotkeyHint(hotkey, options?)`         | Get a computed ref of whether held modifiers should reveal a shortcut's hint. False unless a registration of the hotkey can fire: enabled, in an active scope, and with focus inside its element target. |
| `useKeyHold(key)`                         | Get a ref of whether one key is held. Letters match in any case; other names, such as `Shift`, are case-sensitive.                                                                                       |
| `useHeldKeys()`                           | Get a ref of every key that's held right now.                                                                                                                                                            |
| `useHeldKeyCodes()`                       | Get a ref mapping each held key to its physical `event.code`.                                                                                                                                            |

The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.

No provider is required. Call the composables synchronously in setup.

## Pitfalls

- **Pass the ref, not `.value`.** `{ enabled: isDirty.value }` is read once, so the hotkey never turns on, and `{ target: panel.value }` is `null` in setup, so the hotkey never registers. Pass `isDirty` and `panel`. `enabled` and `target` accept refs and getters; for other options that depend on state, pass a getter for the whole options object.
- **A component ref listens on the component's root element.** `useTemplateRef<InstanceType<typeof Panel>>('panel')` works as `target`. The root element is read when the ref is set: a component with more than one root node or a text root registers nothing, and a root the component adds or swaps later (`v-if` on the root) isn't followed. Put the ref on an element instead.
- **Put the provider around the dialog component.** A `HotkeysProvider` in a component's own template, or `provideHotkeysContext` in its own setup, applies only to its children. Register the dialog's hotkeys in a child component, and give each open dialog its own scope name, such as `` `dialog-${useId()}` ``.
- **Destructure the recorder.** Templates unwrap only top-level refs, so `v-if="recorder.isRecording"` is always true. Use `const { isRecording, startRecording } = useHotkeyRecorder(...)`.
- **The callback isn't tracked.** Read refs and props inside it.
- **Call the composables directly.** A `useShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, reactive options, and app hotkeys.
- **Server-rendered labels need the user's platform.** On the server, `formatForDisplay` can't see the user's OS, so it renders Linux labels that differ after hydration for Mac and Windows users. Set the provider's `defaultOptions.platform` to `detectPlatform(userAgent)` from the request's `User-Agent` header, and format labels with `const format = useFormatForDisplay()` in `setup`, then `format(hotkey)`. Keep plain `formatForDisplay` for labels that render only in the browser, when no provider sets `platform`.

When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Vue](./references/app-hotkeys.md).

## API discovery and docs

Signatures: `node_modules/@tanstack/vue-hotkeys/dist/*.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/vue/guides/<page>.md`, such as `hotkeys`, `hotkeys-provider-and-scopes`, or `app-hotkeys`. Devtools: `HotkeysDevtoolsPanel` from `@tanstack/vue-hotkeys-devtools`.

