TanStack Hotkeys in Solid
Before starting, load the @tanstack/hotkeys#hotkeys-core skill (npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core).
import { createHotkey } from '@tanstack/solid-hotkeys'
import { createSignal } from 'solid-js'
export function Editor() {
const [isDirty, setIsDirty] = createSignal(false)
const [panel, setPanel] = createSignal<HTMLDivElement | null>(null)
createHotkey(
'Mod+S',
() => save(),
() => ({ enabled: isDirty() }),
)
createHotkey(
'Escape',
() => closePanel(),
() => ({ target: panel() }),
)
return <div ref={setPanel} tabIndex={0} => setIsDirty(true)} />
}
API
| API |
What it's for |
createHotkey(hotkey, callback, options?) |
Register one chord, sequence, or app hotkey for the owning component's lifetime; the hotkey and options can be accessors. |
createHotkeys(definitions, commonOptions?) |
Register several hotkeys, or an accessor of a list built from data, in one call. |
<HotkeysProvider> |
Set default options, a scope (exclusive for dialogs), enabled, and app hotkeys for the components inside it. |
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. |
createFormatForDisplay() |
Get formatForDisplay with the provider's platform filled in, for labels in server-rendered apps. |
useAppHotkeys() |
Get an accessor of the declared app hotkeys with the user's custom hotkeys applied. |
createAppHotkeyList() |
Get an accessor 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. |
createHotkeyRecorder(options) |
Record a chord or sequence the user presses; its state fields are accessors. |
createHotkeyRegistrations() |
Get an accessor listing every registered hotkey with its options, meta, and status (whether it's enabled and in an active scope). |
createHotkeyScopesState() |
Get an accessor of the active scopes and the exclusive scope that owns the keyboard. |
createHotkeyHint(hotkey, options?) |
Get an accessor 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. |
createKeyHold(key) |
Get an accessor of whether one key is held. Letters match in any case; other names, such as Shift, are case-sensitive. |
createHeldKeys() |
Get an accessor of every key that's held right now. |
createHeldKeyCodes() |
Get an accessor mapping each held key to its physical event.code. |
The package also re-exports @tanstack/hotkeys, such as formatForDisplay, matchesKeyboardEvent, and defineAppHotkeys.
The state these return is accessors, including the recorder's fields. No provider is required.
Pitfalls
- Pass options as an accessor.
{ enabled: isDirty() } is read once, during setup, so the hotkey never follows the signal. Use () => ({ enabled: isDirty() }). The hotkey and createHotkeys' definitions also accept accessors.
- Keep element targets in a signal. A
let el variable is still undefined when the options are read, and nothing tracks it, so the hotkey waits and never registers. Use ref={setEl} and () => ({ target: el() }); a null or undefined target waits for the element.
- Register hotkeys for removable elements in their
ref. Solid never calls a ref with null, so a signal keeps an element that <Show> or <For> removed, and the hotkey stays registered on it. Use ref={(el) => createHotkey('K', cb, { target: el })}; the hotkey unregisters when the element is removed.
- The callback isn't tracked. Read props inside it, as
() => props.onClose(), rather than passing props.onClose itself.
- Register a dialog's hotkeys in a child of its provider. A primitive uses the nearest
HotkeysProvider above its component, so a dialog that renders <HotkeysProvider scope={...} exclusive> and creates Escape itself puts it in the suspended outer scope. Give each open dialog its own scope name, such as `dialog-${createUniqueId()}`.
- Call the primitives directly. A
createShortcut(keys: string) wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, accessor 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 = createFormatForDisplay() in the component, 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 Solid.
API discovery and docs
Signatures: node_modules/@tanstack/solid-hotkeys/dist/*.d.ts. Guides: https://tanstack.com/hotkeys/latest/docs/framework/solid/guides/<page>.md, such as hotkeys, hotkeys-provider-and-scopes, or app-hotkeys. Devtools: hotkeysDevtoolsPlugin() from @tanstack/solid-hotkeys-devtools in @tanstack/solid-devtools.
1---2name: tanstack-solid-hotkeys3description: "Use when adding or fixing keyboard shortcuts in a SolidJS app with @tanstack/solid-hotkeys: createHotkey and createHotkeys, accessor options and signal targets, HotkeysProvider defaults and dialog scopes, app hotkey primitives, recorders, held-key and hint primitives, or replacing onMount keydown listeners."4license: "MIT"5metadata:6 source: https://skillmd.com/skills/lukasa1993/tanstack-solid-hotkeys7 internal: true8 tanstack-framework: "solid"9 tanstack-library: "@tanstack/solid-hotkeys"10 tanstack-library-version: "0.15.0"11 tanstack-package: "@tanstack/solid-hotkeys"12 tanstack-package-version: "0.22.1"13 tanstack-purpose: "Solid bindings for TanStack Hotkeys: primitives, accessors, providers, and the Solid-specific reactivity mistakes to avoid."14 tanstack-requires: "[\"tanstack-hotkeys-core\"]"15 tanstack-source-skill: "solid-hotkeys"16 tanstack-sources: "[\"src/createHotkey.ts\",\"src/createHotkeys.ts\",\"src/HotkeysProvider.tsx\",\"src/appHotkeys.ts\",\"TanStack/hotkeys:docs/framework/solid/quick-start.md\",\"TanStack/hotkeys:docs/framework/solid/guides/hotkeys-provider-and-scopes.md\"]"17 tanstack-type: "framework"18---1920# TanStack Hotkeys in Solid2122Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).2324```tsx25import { createHotkey } from '@tanstack/solid-hotkeys'26import { createSignal } from 'solid-js'2728export function Editor() {29 const [isDirty, setIsDirty] = createSignal(false)30 const [panel, setPanel] = createSignal<HTMLDivElement | null>(null)3132 createHotkey(33 'Mod+S',34 () => save(),35 () => ({ enabled: isDirty() }),36 )37 createHotkey(38 'Escape',39 () => closePanel(),40 () => ({ target: panel() }),41 )4243 return <div ref={setPanel} tabIndex={0} onInput={() => setIsDirty(true)} />44}45```4647## API4849| API | What it's for |50| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |51| `createHotkey(hotkey, callback, options?)` | Register one chord, sequence, or app hotkey for the owning component's lifetime; the hotkey and options can be accessors. |52| `createHotkeys(definitions, commonOptions?)` | Register several hotkeys, or an accessor of a list built from data, in one call. |53| `<HotkeysProvider>` | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it. |54| `useHotkeysContext()` | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider. |55| `useDefaultHotkeysOptions()` | Read the default options merged from every provider above. |56| `createFormatForDisplay()` | Get `formatForDisplay` with the provider's `platform` filled in, for labels in server-rendered apps. |57| `useAppHotkeys()` | Get an accessor of the declared app hotkeys with the user's custom hotkeys applied. |58| `createAppHotkeyList()` | Get an accessor listing every app hotkey with its status, for a cheat sheet or settings screen. |59| `useCustomHotkeys()` | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts. |60| `createHotkeyRecorder(options)` | Record a chord or sequence the user presses; its state fields are accessors. |61| `createHotkeyRegistrations()` | Get an accessor listing every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope). |62| `createHotkeyScopesState()` | Get an accessor of the active scopes and the exclusive scope that owns the keyboard. |63| `createHotkeyHint(hotkey, options?)` | Get an accessor 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. |64| `createKeyHold(key)` | Get an accessor of whether one key is held. Letters match in any case; other names, such as `Shift`, are case-sensitive. |65| `createHeldKeys()` | Get an accessor of every key that's held right now. |66| `createHeldKeyCodes()` | Get an accessor mapping each held key to its physical `event.code`. |6768The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.6970The state these return is accessors, including the recorder's fields. No provider is required.7172## Pitfalls7374- **Pass options as an accessor.** `{ enabled: isDirty() }` is read once, during setup, so the hotkey never follows the signal. Use `() => ({ enabled: isDirty() })`. The hotkey and `createHotkeys`' definitions also accept accessors.75- **Keep element targets in a signal.** A `let el` variable is still `undefined` when the options are read, and nothing tracks it, so the hotkey waits and never registers. Use `ref={setEl}` and `() => ({ target: el() })`; a `null` or `undefined` target waits for the element.76- **Register hotkeys for removable elements in their `ref`.** Solid never calls a `ref` with `null`, so a signal keeps an element that `<Show>` or `<For>` removed, and the hotkey stays registered on it. Use `ref={(el) => createHotkey('K', cb, { target: el })}`; the hotkey unregisters when the element is removed.77- **The callback isn't tracked.** Read props inside it, as `() => props.onClose()`, rather than passing `props.onClose` itself.78- **Register a dialog's hotkeys in a child of its provider.** A primitive uses the nearest `HotkeysProvider` above its component, so a dialog that renders `<HotkeysProvider scope={...} exclusive>` and creates `Escape` itself puts it in the suspended outer scope. Give each open dialog its own scope name, such as `` `dialog-${createUniqueId()}` ``.79- **Call the primitives directly.** A `createShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, accessor options, and app hotkeys.80- **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 = createFormatForDisplay()` in the component, then `format(hotkey)`. Keep plain `formatForDisplay` for labels that render only in the browser, when no provider sets `platform`.8182When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Solid](./references/app-hotkeys.md).8384## API discovery and docs8586Signatures: `node_modules/@tanstack/solid-hotkeys/dist/*.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/solid/guides/<page>.md`, such as `hotkeys`, `hotkeys-provider-and-scopes`, or `app-hotkeys`. Devtools: `hotkeysDevtoolsPlugin()` from `@tanstack/solid-hotkeys-devtools` in `@tanstack/solid-devtools`.