TanStack Hotkeys in Alpine
Before starting, load the @tanstack/hotkeys#hotkeys-core skill (npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core).
import { createHotkeysScope, hotkeysPlugin } from '@tanstack/alpine-hotkeys'
import Alpine from 'alpinejs'
Alpine.plugin(hotkeysPlugin) // before Alpine.start()
Alpine.data('panel', () => ({
dirty: false,
hotkeys: createHotkeysScope(),
init() {
this.hotkeys.createHotkey(
'Mod+S',
() => save(),
() => ({ enabled: this.dirty }),
)
this.hotkeys.createHotkey(
'Escape',
() => closePanel(),
() => ({ target: this.$refs.panel }),
)
},
destroy() {
this.hotkeys.destroy()
},
}))
Install Alpine.plugin(hotkeysPlugin) before Alpine.start(). It gives the adapter the app's Alpine instance; without it, the adapter falls back to window.Alpine and throws when neither exists. The plugin also adds the $hotkeys magic for markup-only components, which is destroyed with its element: x-init="$hotkeys.createHotkey('Mod+S', () => save())".
API
| API |
What it's for |
Alpine.plugin(hotkeysPlugin) |
Give the adapter the app's Alpine, and install the $hotkeys magic, an owner destroyed with its element. |
createHotkeysScope(defaults?) |
Create an owner for one Alpine.data component, with optional default options. |
createHotkeyRecorder(owner, options) |
Record a chord or sequence the user presses, for a settings screen. The owner destroys it and supplies its hotkeyRecorder defaults. |
Alpine.plugin(hotkeyRecorderPlugin) |
Install the $hotkeyRecorder(options) magic, which creates recorders destroyed with their element. |
provideAppHotkeys(appHotkeys, options?) |
Declare app hotkeys and load the user's custom hotkeys once at startup, since Alpine has no provider. |
getHotkeyManager().activateScope(scope, options?) |
Turn on a scope, such as an exclusive one for a dialog; it returns the function that turns the scope off. |
Each owner has these methods. Read their state through .value, or .hotkeys for registrations.
| Method |
What it's for |
createHotkey(hotkey, callback, options?) |
Register one chord, sequence, or app hotkey until the owner is destroyed; options can be a getter. |
createHotkeys(definitions, commonOptions?) |
Register several hotkeys, or a getter of a list built from data, in one call. |
createAppHotkeys() |
Get the declared app hotkeys with the user's custom hotkeys applied. |
createAppHotkeyList() |
List every app hotkey with its status, for a cheat sheet or settings screen. |
createCustomHotkeys() |
Read, change, and reset the user's custom hotkeys, and check a new one for conflicts. |
createHotkeyRegistrations() |
List every registered hotkey with its options, meta, and status (whether it's enabled and in an active scope). |
createHotkeyScopesState() |
Get the active scopes and the exclusive scope that owns the keyboard. |
createHotkeyHint(hotkey, options?) |
Get 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. |
createKeyHold(key) |
Get whether one key is held. Letters match in any case; other names, such as Shift, are case-sensitive. |
createHeldKeys() |
Get every key that's held right now. |
createHeldKeyCodes() |
Map each held key to its physical event.code. |
destroy() |
Release every hotkey, subscription, and recorder the owner created. |
The package also re-exports @tanstack/hotkeys, such as formatForDisplay, matchesKeyboardEvent, and defineAppHotkeys.
Pitfalls
- Destroy each owner. Owners aren't tied to Alpine's lifecycle, so without
this.hotkeys.destroy() in destroy(), a removed component's hotkeys keep firing. Create one owner per component instance, inside the Alpine.data factory.
createHotkeysScope isn't a hotkey scope. It only owns registrations and sets defaults. For a dialog, activate a real scope in init() with release = getHotkeyManager().activateScope(name, { exclusive: true }), pass { scope: name } to the dialog's hotkeys, and call release() in destroy(). Give each open dialog its own name.
- Pass options as a getter.
{ enabled: this.dirty } is read once. Use () => ({ enabled: this.dirty }).
- Use either
$hotkeys or your own owner for a hotkey, not both. Otherwise it registers twice.
- Call
create* in x-init or init(), and read .value anywhere. Calling create* inside a reactive expression such as x-text="$hotkeys.createHeldKeys().value" creates a new subscription on every evaluation.
- Owners have no
createHotkeyRecorder method since v0.10.0. Call createHotkeyRecorder(this.hotkeys, options), so apps that don't record don't ship the recorder.
- With server rendering, load the adapter only in the browser.
When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load @tanstack/hotkeys#app-hotkeys and read app hotkeys in Alpine.
API discovery and docs
Signatures: node_modules/@tanstack/alpine-hotkeys/dist/types.d.ts. Guides: https://tanstack.com/hotkeys/latest/docs/framework/alpine/guides/<page>.md, such as hotkeys or app-hotkeys.
1---2name: tanstack-alpine-hotkeys3description: "Use when adding or fixing keyboard shortcuts in an Alpine.js app with @tanstack/alpine-hotkeys: createHotkeysScope owners, the $hotkeys magic and hotkeysPlugin, getter options, element targets with $refs, scopes activated from the hotkey manager, app hotkeys, recorders, and held keys, or replacing @keydown.window handlers."4license: "MIT"5metadata:6 source: https://skillmd.com/skills/lukasa1993/tanstack-alpine-hotkeys7 internal: true8 tanstack-framework: "alpine"9 tanstack-library: "@tanstack/alpine-hotkeys"10 tanstack-library-version: "0.4.0"11 tanstack-package: "@tanstack/alpine-hotkeys"12 tanstack-package-version: "0.12.1"13 tanstack-purpose: "Alpine bindings for TanStack Hotkeys: per-component owners, the $hotkeys magic, getter options, manager-activated scopes, and the Alpine-specific mistakes to avoid."14 tanstack-requires: "[\"tanstack-hotkeys-core\"]"15 tanstack-source-skill: "alpine-hotkeys"16 tanstack-sources: "[\"src/createHotkeysScope.ts\",\"src/hotkeysPlugin.ts\",\"src/createHotkeyRecorder.ts\",\"src/hotkeyRecorderPlugin.ts\",\"src/scope.ts\",\"src/createHotkey.ts\",\"src/createAppHotkeys.ts\",\"TanStack/hotkeys:docs/framework/alpine/quick-start.md\",\"TanStack/hotkeys:docs/framework/alpine/guides/app-hotkeys.md\"]"17 tanstack-type: "framework"18---1920# TanStack Hotkeys in Alpine2122Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).2324```ts no-check25import { createHotkeysScope, hotkeysPlugin } from '@tanstack/alpine-hotkeys'26import Alpine from 'alpinejs'2728Alpine.plugin(hotkeysPlugin) // before Alpine.start()2930Alpine.data('panel', () => ({31 dirty: false,32 hotkeys: createHotkeysScope(),33 init() {34 this.hotkeys.createHotkey(35 'Mod+S',36 () => save(),37 () => ({ enabled: this.dirty }),38 )39 this.hotkeys.createHotkey(40 'Escape',41 () => closePanel(),42 () => ({ target: this.$refs.panel }),43 )44 },45 destroy() {46 this.hotkeys.destroy()47 },48}))49```5051Install `Alpine.plugin(hotkeysPlugin)` before `Alpine.start()`. It gives the adapter the app's Alpine instance; without it, the adapter falls back to `window.Alpine` and throws when neither exists. The plugin also adds the `$hotkeys` magic for markup-only components, which is destroyed with its element: `x-init="$hotkeys.createHotkey('Mod+S', () => save())"`.5253## API5455| API | What it's for |56| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |57| `Alpine.plugin(hotkeysPlugin)` | Give the adapter the app's Alpine, and install the `$hotkeys` magic, an owner destroyed with its element. |58| `createHotkeysScope(defaults?)` | Create an owner for one `Alpine.data` component, with optional default options. |59| `createHotkeyRecorder(owner, options)` | Record a chord or sequence the user presses, for a settings screen. The owner destroys it and supplies its `hotkeyRecorder` defaults. |60| `Alpine.plugin(hotkeyRecorderPlugin)` | Install the `$hotkeyRecorder(options)` magic, which creates recorders destroyed with their element. |61| `provideAppHotkeys(appHotkeys, options?)` | Declare app hotkeys and load the user's custom hotkeys once at startup, since Alpine has no provider. |62| `getHotkeyManager().activateScope(scope, options?)` | Turn on a scope, such as an exclusive one for a dialog; it returns the function that turns the scope off. |6364Each owner has these methods. Read their state through `.value`, or `.hotkeys` for registrations.6566| Method | What it's for |67| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |68| `createHotkey(hotkey, callback, options?)` | Register one chord, sequence, or app hotkey until the owner is destroyed; options can be a getter. |69| `createHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a getter of a list built from data, in one call. |70| `createAppHotkeys()` | Get the declared app hotkeys with the user's custom hotkeys applied. |71| `createAppHotkeyList()` | List every app hotkey with its status, for a cheat sheet or settings screen. |72| `createCustomHotkeys()` | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts. |73| `createHotkeyRegistrations()` | List every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope). |74| `createHotkeyScopesState()` | Get the active scopes and the exclusive scope that owns the keyboard. |75| `createHotkeyHint(hotkey, options?)` | Get 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. |76| `createKeyHold(key)` | Get whether one key is held. Letters match in any case; other names, such as `Shift`, are case-sensitive. |77| `createHeldKeys()` | Get every key that's held right now. |78| `createHeldKeyCodes()` | Map each held key to its physical `event.code`. |79| `destroy()` | Release every hotkey, subscription, and recorder the owner created. |8081The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.8283## Pitfalls8485- **Destroy each owner.** Owners aren't tied to Alpine's lifecycle, so without `this.hotkeys.destroy()` in `destroy()`, a removed component's hotkeys keep firing. Create one owner per component instance, inside the `Alpine.data` factory.86- **`createHotkeysScope` isn't a hotkey scope.** It only owns registrations and sets defaults. For a dialog, activate a real scope in `init()` with `release = getHotkeyManager().activateScope(name, { exclusive: true })`, pass `{ scope: name }` to the dialog's hotkeys, and call `release()` in `destroy()`. Give each open dialog its own name.87- **Pass options as a getter.** `{ enabled: this.dirty }` is read once. Use `() => ({ enabled: this.dirty })`.88- **Use either `$hotkeys` or your own owner for a hotkey, not both.** Otherwise it registers twice.89- **Call `create*` in `x-init` or `init()`, and read `.value` anywhere.** Calling `create*` inside a reactive expression such as `x-text="$hotkeys.createHeldKeys().value"` creates a new subscription on every evaluation.90- **Owners have no `createHotkeyRecorder` method** since v0.10.0. Call `createHotkeyRecorder(this.hotkeys, options)`, so apps that don't record don't ship the recorder.91- With server rendering, load the adapter only in the browser.9293When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Alpine](./references/app-hotkeys.md).9495## API discovery and docs9697Signatures: `node_modules/@tanstack/alpine-hotkeys/dist/types.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/alpine/guides/<page>.md`, such as `hotkeys` or `app-hotkeys`.