TanStack Hotkeys in Svelte
Before starting, load the @tanstack/hotkeys#hotkeys-core skill (npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core).
<script lang="ts">
import {
createHotkey,
createHotkeyAttachment,
} from '@tanstack/svelte-hotkeys'
let isDirty = $state(false)
createHotkey(
'Mod+S',
() => save(),
() => ({ enabled: isDirty }),
)
const closeOnEscape = createHotkeyAttachment('Escape', () => closePanel())
</script>
<div tabindex="0" {@attach closeOnEscape} => (isDirty = true)}>
Panel
</div>
API
| API |
What it's for |
createHotkey(hotkey, callback, options?) |
Register one chord, sequence, or app hotkey on the document while the component is mounted; pass getters for values that change. |
createHotkeys(definitions, commonOptions?) |
Register several hotkeys on the document, or a getter of a list built from data. |
createHotkeyAttachment(hotkey, callback, options?) |
Create an attachment for {@attach} that listens on one element. |
createHotkeysAttachment(definitions, commonOptions?) |
Create an attachment that registers several hotkeys on one element. |
<HotkeysProvider> |
Set default options, a scope (exclusive for dialogs), enabled, and app hotkeys for the components inside it. |
setHotkeysContext(options) |
Set the same options from a component's script instead of rendering HotkeysProvider; they apply to that component too. |
getHotkeysContext() |
Read the nearest context's merged defaults and enabled state, or null outside one. |
getDefaultHotkeysOptions() |
Read the default options merged from every context above. |
getFormatForDisplay() |
Get formatForDisplay with the provider's platform filled in, for labels in server-rendered apps. Call it during component initialization. |
getAppHotkeys() |
Read .current, the declared app hotkeys with the user's custom hotkeys applied. |
getAppHotkeyList() |
Read .current, every app hotkey with its status, for a cheat sheet or settings screen. |
getCustomHotkeys() |
Read the user's custom hotkeys from .current, change or reset them, and check a new one for conflicts. |
createHotkeyRecorder(options) |
Record a chord or sequence the user presses, for a settings screen. |
getHotkeyRegistrations() |
Read .hotkeys, every registered hotkey with its options, meta, and status (whether it's enabled and in an active scope). |
getHotkeyScopesState() |
Read .state, the active scopes and the exclusive scope that owns the keyboard. |
getHotkeyHint(hotkey, options?) |
Read .visible, 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. |
getIsKeyHeld(key) |
Read .held, whether one key is held. Letters match in any case; other names, such as Shift, are case-sensitive. |
getHeldKeys() |
Read .keys, every key that's held right now. |
getHeldKeyCodesMap() |
Read .codes, which maps 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 these at the top level of a component's <script>.
Pitfalls
- Pass options as a getter.
{ enabled: isDirty } is read once, during initialization, so the hotkey never follows the state. Use () => ({ enabled: isDirty }). The hotkey and createHotkeys' definitions also accept getters.
- Don't destructure the returned objects.
const { held } = getIsKeyHeld('Shift') copies the value once. Keep the object and read shift.held, recorder.isRecording, or appHotkeys.current where you use it.
- Use attachments for element hotkeys. The
target option takes only document or window.
- Call
setHotkeysContext before creating the component's hotkeys. It applies to the component itself, so a hotkey created first lands in the outer scope, which an exclusive context then suspends. It reads its options once; for enabled or exclusive that change, wrap the component in <HotkeysProvider>. Give each open dialog its own scope name.
- The callback isn't tracked. Read state and props inside it.
- Call the functions directly. A
createShortcut(keys: string) wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, getter 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 = getFormatForDisplay() during component initialization, 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 Svelte.
API discovery and docs
Signatures: node_modules/@tanstack/svelte-hotkeys/dist/*.d.ts. Guides: https://tanstack.com/hotkeys/latest/docs/framework/svelte/guides/<page>.md, such as hotkeys, hotkeys-provider-and-scopes, or app-hotkeys. Devtools: hotkeysDevtoolsPlugin() from @tanstack/svelte-hotkeys-devtools in @tanstack/svelte-devtools.
1---2name: tanstack-svelte-hotkeys3description: "Use when adding or fixing keyboard shortcuts in a Svelte 5 app with @tanstack/svelte-hotkeys: createHotkey and createHotkeys, getter options, createHotkeyAttachment for element hotkeys, HotkeysProvider and setHotkeysContext scopes, app hotkey getters, recorders, held-key and hint getters, or replacing svelte:window keydown handlers."4license: "MIT"5metadata:6 source: https://skillmd.com/skills/lukasa1993/tanstack-svelte-hotkeys7 internal: true8 tanstack-framework: "svelte"9 tanstack-library: "@tanstack/svelte-hotkeys"10 tanstack-library-version: "0.15.0"11 tanstack-package: "@tanstack/svelte-hotkeys"12 tanstack-package-version: "0.22.1"13 tanstack-purpose: "Svelte 5 bindings for TanStack Hotkeys: getters, attachments, providers, and the Svelte-specific reactivity mistakes to avoid."14 tanstack-requires: "[\"tanstack-hotkeys-core\"]"15 tanstack-source-skill: "svelte-hotkeys"16 tanstack-sources: "[\"src/createHotkey.svelte.ts\",\"src/createHotkeys.svelte.ts\",\"src/HotkeysCtx.ts\",\"src/HotkeysProvider.svelte\",\"src/getAppHotkeys.svelte.ts\",\"src/createHotkeyRecorder.svelte.ts\",\"TanStack/hotkeys:docs/framework/svelte/quick-start.md\",\"TanStack/hotkeys:docs/framework/svelte/guides/hotkeys-provider-and-scopes.md\"]"17 tanstack-type: "framework"18---1920# TanStack Hotkeys in Svelte2122Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).2324```svelte25<script lang="ts">26 import {27 createHotkey,28 createHotkeyAttachment,29 } from '@tanstack/svelte-hotkeys'3031 let isDirty = $state(false)3233 createHotkey(34 'Mod+S',35 () => save(),36 () => ({ enabled: isDirty }),37 )38 const closeOnEscape = createHotkeyAttachment('Escape', () => closePanel())39</script>4041<div tabindex="0" {@attach closeOnEscape} oninput={() => (isDirty = true)}>42 Panel43</div>44```4546## API4748| API | What it's for |49| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |50| `createHotkey(hotkey, callback, options?)` | Register one chord, sequence, or app hotkey on the document while the component is mounted; pass getters for values that change. |51| `createHotkeys(definitions, commonOptions?)` | Register several hotkeys on the document, or a getter of a list built from data. |52| `createHotkeyAttachment(hotkey, callback, options?)` | Create an attachment for `{@attach}` that listens on one element. |53| `createHotkeysAttachment(definitions, commonOptions?)` | Create an attachment that registers several hotkeys on one element. |54| `<HotkeysProvider>` | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it. |55| `setHotkeysContext(options)` | Set the same options from a component's script instead of rendering `HotkeysProvider`; they apply to that component too. |56| `getHotkeysContext()` | Read the nearest context's merged defaults and enabled state, or `null` outside one. |57| `getDefaultHotkeysOptions()` | Read the default options merged from every context above. |58| `getFormatForDisplay()` | Get `formatForDisplay` with the provider's `platform` filled in, for labels in server-rendered apps. Call it during component initialization. |59| `getAppHotkeys()` | Read `.current`, the declared app hotkeys with the user's custom hotkeys applied. |60| `getAppHotkeyList()` | Read `.current`, every app hotkey with its status, for a cheat sheet or settings screen. |61| `getCustomHotkeys()` | Read the user's custom hotkeys from `.current`, change or reset them, and check a new one for conflicts. |62| `createHotkeyRecorder(options)` | Record a chord or sequence the user presses, for a settings screen. |63| `getHotkeyRegistrations()` | Read `.hotkeys`, every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope). |64| `getHotkeyScopesState()` | Read `.state`, the active scopes and the exclusive scope that owns the keyboard. |65| `getHotkeyHint(hotkey, options?)` | Read `.visible`, 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. |66| `getIsKeyHeld(key)` | Read `.held`, whether one key is held. Letters match in any case; other names, such as `Shift`, are case-sensitive. |67| `getHeldKeys()` | Read `.keys`, every key that's held right now. |68| `getHeldKeyCodesMap()` | Read `.codes`, which maps each held key to its physical `event.code`. |6970The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.7172No provider is required. Call these at the top level of a component's `<script>`.7374## Pitfalls7576- **Pass options as a getter.** `{ enabled: isDirty }` is read once, during initialization, so the hotkey never follows the state. Use `() => ({ enabled: isDirty })`. The hotkey and `createHotkeys`' definitions also accept getters.77- **Don't destructure the returned objects.** `const { held } = getIsKeyHeld('Shift')` copies the value once. Keep the object and read `shift.held`, `recorder.isRecording`, or `appHotkeys.current` where you use it.78- **Use attachments for element hotkeys.** The `target` option takes only `document` or `window`.79- **Call `setHotkeysContext` before creating the component's hotkeys.** It applies to the component itself, so a hotkey created first lands in the outer scope, which an exclusive context then suspends. It reads its options once; for `enabled` or `exclusive` that change, wrap the component in `<HotkeysProvider>`. Give each open dialog its own scope name.80- **The callback isn't tracked.** Read state and props inside it.81- **Call the functions directly.** A `createShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, getter options, and app hotkeys.82- **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 = getFormatForDisplay()` during component initialization, then `format(hotkey)`. Keep plain `formatForDisplay` for labels that render only in the browser, when no provider sets `platform`.8384When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Svelte](./references/app-hotkeys.md).8586## API discovery and docs8788Signatures: `node_modules/@tanstack/svelte-hotkeys/dist/*.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/svelte/guides/<page>.md`, such as `hotkeys`, `hotkeys-provider-and-scopes`, or `app-hotkeys`. Devtools: `hotkeysDevtoolsPlugin()` from `@tanstack/svelte-hotkeys-devtools` in `@tanstack/svelte-devtools`.