TanStack Hotkeys in Octane
Before starting, load the @tanstack/hotkeys#hotkeys-core skill (npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core).
import { useState } from 'octane'
import { formatForDisplay, useHotkey } from '@tanstack/octane-hotkeys'
export function Panel({ onSave }: { onSave: () => void }) @{
const [panel, setPanel] = useState<HTMLDivElement | null>(null)
useHotkey('Mod+S', () => onSave(), { meta: { name: 'Save' } })
useHotkey('Escape', () => closePanel(), { target: panel })
<div ref={setPanel} tabIndex={0}>
Save <kbd>{formatForDisplay('Mod+S')}</kbd>
</div>
}
API
| API |
What it's for |
useHotkey(hotkey, callback, options?) |
Register one chord, sequence, or app hotkey while the component is mounted. |
useHotkeys(definitions, commonOptions?) |
Register several hotkeys, or 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. |
useFormatForDisplay() |
Get formatForDisplay with the provider's platform filled in. Use it for labels in server-rendered apps; call it at the top of the component. |
useAppHotkeys() |
Get the declared app hotkeys with the user's custom hotkeys applied, to pass to the register API. |
useAppHotkeyList() |
List every app hotkey with its status, including ones whose components aren't mounted, 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, for a settings screen. |
useHotkeyRegistrations() |
List every registered hotkey with its options, meta, and status (whether it's enabled and in an active scope), for a cheat sheet of what's mounted. |
useHotkeyScopesState() |
Get the active scopes and the exclusive scope that owns the keyboard. |
useHotkeyHint(hotkey, options?) |
Get whether held modifiers should reveal a shortcut's hint, such as labels that appear while Mod is held. False unless a registration of the hotkey can fire: enabled, in an active scope, and with focus inside its element target. |
useKeyHold(key) |
Get whether one key is held, such as Shift for a range-select mode. Letters match in any case; other names, such as Shift, are case-sensitive. |
useHeldKeys() |
Get every key that's held right now. |
useHeldKeyCodes() |
Map 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. Use Octane 0.12 or newer, with hooks in compiler-enabled .tsrx components.
Pitfalls
- Keep elements that mount later in state. A ref object such as
useRef<HTMLDivElement | null>(null) works as target, but the hook reads ref.current only after its component renders, so it misses an element that mounts later, such as one a child shows from its own state. Keep such an element in state with a callback ref, as above. A null or undefined target, or an unset ref, waits for the element.
- Register a dialog's hotkeys in a child of its provider. A hook uses the nearest
HotkeysProvider above its component, so a dialog that renders <HotkeysProvider scope={...} exclusive> and registers Escape itself puts it in the suspended outer scope. Give each open dialog its own scope name, such as `dialog-${useId()}`.
- Hooks are tracked by call site. Use
useHotkeys(items.map(...)) for lists, not useHotkey in a loop.
- Custom hooks in plain
.ts and .js files need the compiler. Calls from a .ts or .js file that the compiler skips share one slot per hook in each component, even across different custom hooks, so only the last useHotkey call works. The compiler handles a file that imports a value from octane or starts with /** @jsxImportSource octane */. A type-only import doesn't count. .tsrx and .tsx files are fine.
- Call the hooks directly. A
useShortcut(keys: string) wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, 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() at the top of 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 Octane.
API discovery and docs
Signatures: node_modules/@tanstack/octane-hotkeys/dist/*.d.ts. Guides: https://tanstack.com/hotkeys/latest/docs/framework/octane/guides/<page>.md, such as hotkeys, hotkeys-provider-and-scopes, or app-hotkeys.
1---2name: tanstack-octane-hotkeys3description: "Use when adding or fixing keyboard shortcuts in an Octane app with @tanstack/octane-hotkeys: useHotkey and useHotkeys in .tsrx components, element state as targets, HotkeysProvider defaults and dialog scopes, app hotkey hooks, recorders, held-key and hint hooks, or replacing keydown listeners."4license: "MIT"5metadata:6 source: https://skillmd.com/skills/lukasa1993/tanstack-octane-hotkeys7 internal: true8 tanstack-framework: "octane"9 tanstack-library: "@tanstack/octane-hotkeys"10 tanstack-library-version: "0.5.0"11 tanstack-package: "@tanstack/octane-hotkeys"12 tanstack-package-version: "0.12.1"13 tanstack-purpose: "Octane bindings for TanStack Hotkeys: hooks in compiler-enabled .tsrx components, element targets, providers, and the Octane-specific mistakes to avoid."14 tanstack-requires: "[\"tanstack-hotkeys-core\"]"15 tanstack-source-skill: "octane-hotkeys"16 tanstack-sources: "[\"src/useHotkey.ts\",\"src/useHotkeys.ts\",\"src/HotkeysProvider.ts\",\"src/useAppHotkeys.ts\",\"TanStack/hotkeys:docs/framework/octane/quick-start.md\",\"TanStack/hotkeys:docs/framework/octane/guides/hotkeys-provider-and-scopes.md\"]"17 tanstack-type: "framework"18---1920# TanStack Hotkeys in Octane2122Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).2324```tsrx25import { useState } from 'octane'26import { formatForDisplay, useHotkey } from '@tanstack/octane-hotkeys'2728export function Panel({ onSave }: { onSave: () => void }) @{29 const [panel, setPanel] = useState<HTMLDivElement | null>(null)3031 useHotkey('Mod+S', () => onSave(), { meta: { name: 'Save' } })32 useHotkey('Escape', () => closePanel(), { target: panel })3334 <div ref={setPanel} tabIndex={0}>35 Save <kbd>{formatForDisplay('Mod+S')}</kbd>36 </div>37}38```3940## API4142| API | What it's for |43| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |44| `useHotkey(hotkey, callback, options?)` | Register one chord, sequence, or app hotkey while the component is mounted. |45| `useHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a list built from data, in one call. |46| `<HotkeysProvider>` | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it. |47| `useHotkeysContext()` | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider. |48| `useDefaultHotkeysOptions()` | Read the default options merged from every provider above. |49| `useFormatForDisplay()` | Get `formatForDisplay` with the provider's `platform` filled in. Use it for labels in server-rendered apps; call it at the top of the component. |50| `useAppHotkeys()` | Get the declared app hotkeys with the user's custom hotkeys applied, to pass to the register API. |51| `useAppHotkeyList()` | List every app hotkey with its status, including ones whose components aren't mounted, for a cheat sheet or settings screen. |52| `useCustomHotkeys()` | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts. |53| `useHotkeyRecorder(options)` | Record a chord or sequence the user presses, for a settings screen. |54| `useHotkeyRegistrations()` | List every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope), for a cheat sheet of what's mounted. |55| `useHotkeyScopesState()` | Get the active scopes and the exclusive scope that owns the keyboard. |56| `useHotkeyHint(hotkey, options?)` | Get whether held modifiers should reveal a shortcut's hint, such as labels that appear while Mod is held. False unless a registration of the hotkey can fire: enabled, in an active scope, and with focus inside its element target. |57| `useKeyHold(key)` | Get whether one key is held, such as Shift for a range-select mode. Letters match in any case; other names, such as `Shift`, are case-sensitive. |58| `useHeldKeys()` | Get every key that's held right now. |59| `useHeldKeyCodes()` | Map each held key to its physical `event.code`. |6061The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.6263No provider is required. Use Octane 0.12 or newer, with hooks in compiler-enabled `.tsrx` components.6465## Pitfalls6667- **Keep elements that mount later in state.** A ref object such as `useRef<HTMLDivElement | null>(null)` works as `target`, but the hook reads `ref.current` only after its component renders, so it misses an element that mounts later, such as one a child shows from its own state. Keep such an element in state with a callback ref, as above. A `null` or `undefined` target, or an unset ref, waits for the element.68- **Register a dialog's hotkeys in a child of its provider.** A hook uses the nearest `HotkeysProvider` above its component, so a dialog that renders `<HotkeysProvider scope={...} exclusive>` and registers `Escape` itself puts it in the suspended outer scope. Give each open dialog its own scope name, such as `` `dialog-${useId()}` ``.69- **Hooks are tracked by call site.** Use `useHotkeys(items.map(...))` for lists, not `useHotkey` in a loop.70- **Custom hooks in plain `.ts` and `.js` files need the compiler.** Calls from a `.ts` or `.js` file that the compiler skips share one slot per hook in each component, even across different custom hooks, so only the last `useHotkey` call works. The compiler handles a file that imports a value from `octane` or starts with `/** @jsxImportSource octane */`. A type-only import doesn't count. `.tsrx` and `.tsx` files are fine.71- **Call the hooks directly.** A `useShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, options, and app hotkeys.72- **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()` at the top of the component, then `format(hotkey)`. Keep plain `formatForDisplay` for labels that render only in the browser, when no provider sets `platform`.7374When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Octane](./references/app-hotkeys.md).7576## API discovery and docs7778Signatures: `node_modules/@tanstack/octane-hotkeys/dist/*.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/octane/guides/<page>.md`, such as `hotkeys`, `hotkeys-provider-and-scopes`, or `app-hotkeys`.