# Tanstack Octane Hotkeys

> 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.

- Skill: `lukasa1993/tanstack-octane-hotkeys` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add lukasa1993/tanstack-octane-hotkeys`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lukasa1993/tanstack-octane-hotkeys/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: lukasa1993 (https://skillmd.com/u/lukasa1993)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/lukasa1993/tanstack-octane-hotkeys

---


# TanStack Hotkeys in Octane

Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).

```tsrx
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](./references/app-hotkeys.md).

## 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`.

