TanStack Hotkeys in Vue
Before starting, load the @tanstack/hotkeys#hotkeys-core skill (npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core).
<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.
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.
1---2name: tanstack-vue-hotkeys3description: "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."4license: "MIT"5metadata:6 source: https://skillmd.com/skills/lukasa1993/tanstack-vue-hotkeys7 internal: true8 tanstack-framework: "vue"9 tanstack-library: "@tanstack/vue-hotkeys"10 tanstack-library-version: "0.15.0"11 tanstack-package: "@tanstack/vue-hotkeys"12 tanstack-package-version: "0.22.1"13 tanstack-purpose: "Vue bindings for TanStack Hotkeys: composables, reactive options, providers, and the Vue-specific reactivity mistakes to avoid."14 tanstack-requires: "[\"tanstack-hotkeys-core\"]"15 tanstack-source-skill: "vue-hotkeys"16 tanstack-sources: "[\"src/useHotkey.ts\",\"src/useHotkeys.ts\",\"src/HotkeysProvider.tsx\",\"src/HotkeysProviderContext.ts\",\"src/useAppHotkeys.ts\",\"src/useHotkeyRecorder.ts\",\"TanStack/hotkeys:docs/framework/vue/quick-start.md\",\"TanStack/hotkeys:docs/framework/vue/guides/hotkeys-provider-and-scopes.md\"]"17 tanstack-type: "framework"18---1920# TanStack Hotkeys in Vue2122Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).2324```vue25<script setup lang="ts">26import { formatForDisplay, useHotkey } from '@tanstack/vue-hotkeys'27import { ref } from 'vue'2829const isDirty = ref(false)30const panel = ref<HTMLDivElement | null>(null)3132useHotkey('Mod+S', () => save(), { enabled: isDirty })33useHotkey('Escape', () => closePanel(), { target: panel })34</script>3536<template>37 <div ref="panel" tabindex="0" @input="isDirty = true">38 Save <kbd>{{ formatForDisplay('Mod+S') }}</kbd>39 </div>40</template>41```4243## API4445| API | What it's for |46| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |47| `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. |48| `useHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a ref or getter of a list built from data, in one call. |49| `<HotkeysProvider>` | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for its children, and emit `custom-hotkeys-change`. |50| `provideHotkeysContext(options)` | Provide the same options from a component's setup instead of rendering `HotkeysProvider`; they apply to its children. |51| `useHotkeysContext()` | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider. |52| `useDefaultHotkeysOptions()` | Read the default options merged from every provider above. |53| `useFormatForDisplay()` | Get `formatForDisplay` with the provider's `platform` filled in, for labels in server-rendered apps. Call it in `setup`. |54| `useAppHotkeys()` | Get a computed ref of the declared app hotkeys with the user's custom hotkeys applied. |55| `useAppHotkeyList()` | Get a computed ref listing every app hotkey with its status, for a cheat sheet or settings screen. |56| `useCustomHotkeys()` | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts. |57| `useHotkeyRecorder(options)` | Record a chord or sequence the user presses; destructure the refs it returns. |58| `useHotkeyRegistrations()` | Get a ref listing every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope). |59| `useHotkeyScopesState()` | Get a ref of the active scopes and the exclusive scope that owns the keyboard. |60| `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. |61| `useKeyHold(key)` | Get a ref of whether one key is held. Letters match in any case; other names, such as `Shift`, are case-sensitive. |62| `useHeldKeys()` | Get a ref of every key that's held right now. |63| `useHeldKeyCodes()` | Get a ref mapping each held key to its physical `event.code`. |6465The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.6667No provider is required. Call the composables synchronously in setup.6869## Pitfalls7071- **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.72- **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.73- **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()}` ``.74- **Destructure the recorder.** Templates unwrap only top-level refs, so `v-if="recorder.isRecording"` is always true. Use `const { isRecording, startRecording } = useHotkeyRecorder(...)`.75- **The callback isn't tracked.** Read refs and props inside it.76- **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.77- **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`.7879When 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).8081## API discovery and docs8283Signatures: `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`.