App hotkeys
This skill builds on hotkeys-core. The adapter skill's app hotkeys reference shows the wiring in your framework.
App hotkeys are the library's shortcut catalog. Use them instead of a separate shortcut config, context, or hand-written cheat sheet. One module declares every shortcut. The root provider holds the user's custom hotkeys. Components register the declared app hotkeys with their callbacks. Plain hotkeys with meta are enough when a list only needs what is mounted right now.
import { defineAppHotkeys } from '@tanstack/hotkeys'
export const appHotkeys = defineAppHotkeys({
'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save' }, scope: 'document' },
'comment.post': {
hotkey: 'Mod+S',
meta: { name: 'Post comment' },
scope: 'comments',
},
'theme.toggle': { hotkey: null, meta: { name: 'Toggle theme' } },
})
Augment Register in the adapter module you import from, such as declare module '@tanstack/react-hotkeys' { interface Register { appHotkeys: typeof appHotkeys } }, to type ids. Lit, Alpine, and Ember have no provider: call provideAppHotkeys(appHotkeys, options) once at startup. Pass saved data that loads later to store.setOptions({ customHotkeys }) on the returned store; providers apply a changed customHotkeys prop themselves. undefined leaves custom hotkeys unchanged while data loads; null clears them, such as on sign-out.
Pitfalls
- Register the app hotkey, not its value. Pass
appHotkeys['doc.save']. Passing .hotkey registers the declared default, so the user's rebinding never applies, and the list reports the shortcut as 'inactive'.
- Save what
onCustomHotkeysChange receives. It holds only the shortcuts the user changed, so users still get new defaults. Saving every effective hotkey freezes today's defaults into their data.
- Ids are a storage contract. Saved data is keyed by id, and unknown ids are silently dropped, so renaming an id discards users' customizations.
setCustomHotkey returns conflicts and changes nothing when there are any. Check the result before reporting success, or reject the key press earlier by calling findConflicts in the recorder's validate.
- Declare scopes on app hotkeys that share keys. An app hotkey without a scope, or in
'global', conflicts with every other app hotkey on the same keys, so rebinding is rejected.
- Conflict checks treat physical and logical bindings as different. A recorded
Mod+[KeyP] doesn't conflict with a declared Mod+P, although Command+P runs both. Declaring rebindable defaults in the recorder's form, such as Mod+[KeyP], makes them comparable.
- A cheat sheet dialog usually gets an exclusive scope. Register the hotkey that opened it inside the dialog too, so the same keys close it.
When building the "press a new shortcut" control, read recording.
1---2name: tanstack-hotkeys-app-hotkeys3description: "Use when an app built with TanStack Hotkeys needs a keyboard shortcut cheat sheet or help dialog, a command palette whose commands may have shortcuts, a settings screen where users rebind, unbind, or reset shortcuts, recording the shortcut a user presses, conflict checks between shortcuts, or saving custom shortcuts to storage."4license: "MIT"5metadata:6 source: https://skillmd.com/skills/lukasa1993/tanstack-hotkeys-app-hotkeys7 internal: true8 tanstack-library: "@tanstack/hotkeys"9 tanstack-library-version: "0.16.0"10 tanstack-package: "@tanstack/hotkeys"11 tanstack-package-version: "0.27.1"12 tanstack-purpose: "Declare every shortcut once with defineAppHotkeys, then build cheat sheets, rebinding, conflict checks, and persistence from those declarations instead of a parallel shortcut registry."13 tanstack-requires: "[\"tanstack-hotkeys-core\"]"14 tanstack-source-skill: "app-hotkeys"15 tanstack-sources: "[\"src/app-hotkeys.ts\",\"src/hotkey-recorder.ts\",\"src/conflicts.ts\",\"TanStack/hotkeys:docs/framework/react/guides/app-hotkeys.md\",\"TanStack/hotkeys:docs/framework/react/guides/cheat-sheet-ui-helpers.md\",\"TanStack/hotkeys:docs/framework/react/guides/custom-hotkey-recording.md\",\"TanStack/hotkeys:packages/react-hotkeys/tests/skills/shortcut-settings/**\"]"16 tanstack-type: "core"17---1819# App hotkeys2021This skill builds on `hotkeys-core`. The adapter skill's app hotkeys reference shows the wiring in your framework.2223App hotkeys are the library's shortcut catalog. Use them instead of a separate shortcut config, context, or hand-written cheat sheet. One module declares every shortcut. The root provider holds the user's custom hotkeys. Components register the declared app hotkeys with their callbacks. Plain hotkeys with `meta` are enough when a list only needs what is mounted right now.2425```ts26import { defineAppHotkeys } from '@tanstack/hotkeys'2728export const appHotkeys = defineAppHotkeys({29 'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save' }, scope: 'document' },30 'comment.post': {31 hotkey: 'Mod+S',32 meta: { name: 'Post comment' },33 scope: 'comments',34 },35 'theme.toggle': { hotkey: null, meta: { name: 'Toggle theme' } },36})37```3839Augment `Register` in the adapter module you import from, such as `declare module '@tanstack/react-hotkeys' { interface Register { appHotkeys: typeof appHotkeys } }`, to type ids. Lit, Alpine, and Ember have no provider: call `provideAppHotkeys(appHotkeys, options)` once at startup. Pass saved data that loads later to `store.setOptions({ customHotkeys })` on the returned store; providers apply a changed `customHotkeys` prop themselves. `undefined` leaves custom hotkeys unchanged while data loads; `null` clears them, such as on sign-out.4041## Pitfalls4243- **Register the app hotkey, not its value.** Pass `appHotkeys['doc.save']`. Passing `.hotkey` registers the declared default, so the user's rebinding never applies, and the list reports the shortcut as `'inactive'`.44- **Save what `onCustomHotkeysChange` receives.** It holds only the shortcuts the user changed, so users still get new defaults. Saving every effective hotkey freezes today's defaults into their data.45- **Ids are a storage contract.** Saved data is keyed by id, and unknown ids are silently dropped, so renaming an id discards users' customizations.46- **`setCustomHotkey` returns conflicts and changes nothing when there are any.** Check the result before reporting success, or reject the key press earlier by calling `findConflicts` in the recorder's `validate`.47- **Declare scopes on app hotkeys that share keys.** An app hotkey without a scope, or in `'global'`, conflicts with every other app hotkey on the same keys, so rebinding is rejected.48- **Conflict checks treat physical and logical bindings as different.** A recorded `Mod+[KeyP]` doesn't conflict with a declared `Mod+P`, although Command+P runs both. Declaring rebindable defaults in the recorder's form, such as `Mod+[KeyP]`, makes them comparable.49- **A cheat sheet dialog usually gets an exclusive scope.** Register the hotkey that opened it inside the dialog too, so the same keys close it.5051When building the "press a new shortcut" control, read [recording](./references/recording.md).