TanStack Hotkeys in React
Before starting, load the @tanstack/hotkeys#hotkeys-core skill (npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core).
import { formatForDisplay, useHotkey } from '@tanstack/react-hotkeys'
export function SaveButton({ onSave }: { onSave: () => void }) {
useHotkey('Mod+S', () => onSave(), { meta: { name: 'Save' } })
return (
<button
Save <kbd>{formatForDisplay('Mod+S')}</kbd>
</button>
)
}
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. In React Server Components frameworks, call the hooks from client components. The package marks HotkeysProvider as a client component, so a server layout can render it without a 'use client' wrapper.
A dialog that owns the keyboard
import { HotkeysProvider, useHotkey } from '@tanstack/react-hotkeys'
import { useId } from 'react'
import type { ReactNode } from 'react'
export function Dialog(props: { onClose: () => void; children: ReactNode }) {
return (
<HotkeysProvider scope={`dialog-${useId()}`} exclusive>
<DialogBody {...props} />
</HotkeysProvider>
)
}
function DialogBody({
onClose,
children,
}: {
onClose: () => void
children: ReactNode
}) {
useHotkey('Escape', onClose)
return <div role="dialog">{children}</div>
}
A hook uses the nearest HotkeysProvider above its component. Registering Escape in Dialog itself would put it in the outer scope, which the exclusive scope suspends, so the dialog couldn't close. useId gives each open dialog its own scope.
Pitfalls
- Pass the ref, not
ref.current. target: listRef.current is null on the first render, and a null target registers nothing, so the hotkey doesn't work until the component renders again. Pass target: listRef for an element the component always renders.
- Keep elements that mount later in state. The hook reads a ref only after its component renders, so it misses an element that mounts later, such as one a child shows from its own state. Use
const [el, setEl] = useState<HTMLElement | null>(null), target: el, and ref={setEl}; the hotkey registers when the element mounts and unregisters when it unmounts.
- No dependency arrays or
useCallback. The hooks read the hotkey, callback, and options on every render, so inline callbacks always see current state.
- Call the hooks directly. A
useShortcut(keys: string) wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, options, app hotkeys, and the typed callback context.
matchesKeyboardEvent takes the DOM event. In a widget's onKeyDown, pass event.nativeEvent.
- In tests, set
<HotkeysProvider defaultOptions={{ platform: 'mac' }}>. It applies to hotkeys, recorders, labels, and app hotkey conflict checks.
- 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 React.
API discovery and docs
Signatures: node_modules/@tanstack/react-hotkeys/dist/*.d.ts. Guides: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/<page>.md, such as hotkeys, hotkeys-provider-and-scopes, or app-hotkeys. Devtools: hotkeysDevtoolsPlugin() from @tanstack/react-hotkeys-devtools in @tanstack/react-devtools.
1---2name: tanstack-react-hotkeys3description: "Use when adding or fixing keyboard shortcuts in a React app with @tanstack/react-hotkeys: useHotkey and useHotkeys, refs as targets, HotkeysProvider defaults and dialog scopes, app hotkey hooks, recorders, held-key and hint hooks, or replacing useEffect keydown listeners and other React shortcut libraries."4license: "MIT"5metadata:6 source: https://skillmd.com/skills/lukasa1993/tanstack-react-hotkeys7 internal: true8 tanstack-framework: "react"9 tanstack-library: "@tanstack/react-hotkeys"10 tanstack-library-version: "0.15.0"11 tanstack-package: "@tanstack/react-hotkeys"12 tanstack-package-version: "0.23.1"13 tanstack-purpose: "React bindings for TanStack Hotkeys: hooks, providers, refs, and the React-specific mistakes to avoid."14 tanstack-requires: "[\"tanstack-hotkeys-core\"]"15 tanstack-source-skill: "react-hotkeys"16 tanstack-sources: "[\"src/useHotkey.ts\",\"src/useHotkeys.ts\",\"src/HotkeysProvider.tsx\",\"src/useAppHotkeys.ts\",\"src/utils.ts\",\"TanStack/hotkeys:docs/framework/react/quick-start.md\",\"TanStack/hotkeys:docs/framework/react/guides/hotkeys-provider-and-scopes.md\",\"tests/skills/editor-shortcuts/**\",\"tests/skills/shortcut-settings/**\"]"17 tanstack-type: "framework"18---1920# TanStack Hotkeys in React2122Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).2324```tsx25import { formatForDisplay, useHotkey } from '@tanstack/react-hotkeys'2627export function SaveButton({ onSave }: { onSave: () => void }) {28 useHotkey('Mod+S', () => onSave(), { meta: { name: 'Save' } })2930 return (31 <button onClick={onSave}>32 Save <kbd>{formatForDisplay('Mod+S')}</kbd>33 </button>34 )35}36```3738## API3940| API | What it's for |41| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |42| `useHotkey(hotkey, callback, options?)` | Register one chord, sequence, or app hotkey while the component is mounted. |43| `useHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a list built from data, in one call. |44| `<HotkeysProvider>` | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it. |45| `useHotkeysContext()` | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider. |46| `useDefaultHotkeysOptions()` | Read the default options merged from every provider above. |47| `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. |48| `useAppHotkeys()` | Get the declared app hotkeys with the user's custom hotkeys applied, to pass to the register API. |49| `useAppHotkeyList()` | List every app hotkey with its status, including ones whose components aren't mounted, for a cheat sheet or settings screen. |50| `useCustomHotkeys()` | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts. |51| `useHotkeyRecorder(options)` | Record a chord or sequence the user presses, for a settings screen. |52| `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. |53| `useHotkeyScopesState()` | Get the active scopes and the exclusive scope that owns the keyboard. |54| `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. |55| `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. |56| `useHeldKeys()` | Get every key that's held right now. |57| `useHeldKeyCodes()` | Map each held key to its physical `event.code`. |5859The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.6061No provider is required. In React Server Components frameworks, call the hooks from client components. The package marks `HotkeysProvider` as a client component, so a server layout can render it without a `'use client'` wrapper.6263## A dialog that owns the keyboard6465```tsx66import { HotkeysProvider, useHotkey } from '@tanstack/react-hotkeys'67import { useId } from 'react'68import type { ReactNode } from 'react'6970export function Dialog(props: { onClose: () => void; children: ReactNode }) {71 return (72 <HotkeysProvider scope={`dialog-${useId()}`} exclusive>73 <DialogBody {...props} />74 </HotkeysProvider>75 )76}7778function DialogBody({79 onClose,80 children,81}: {82 onClose: () => void83 children: ReactNode84}) {85 useHotkey('Escape', onClose)86 return <div role="dialog">{children}</div>87}88```8990A hook uses the nearest `HotkeysProvider` above its component. Registering `Escape` in `Dialog` itself would put it in the outer scope, which the exclusive scope suspends, so the dialog couldn't close. `useId` gives each open dialog its own scope.9192## Pitfalls9394- **Pass the ref, not `ref.current`.** `target: listRef.current` is `null` on the first render, and a `null` target registers nothing, so the hotkey doesn't work until the component renders again. Pass `target: listRef` for an element the component always renders.95- **Keep elements that mount later in state.** The hook reads a ref only after its component renders, so it misses an element that mounts later, such as one a child shows from its own state. Use `const [el, setEl] = useState<HTMLElement | null>(null)`, `target: el`, and `ref={setEl}`; the hotkey registers when the element mounts and unregisters when it unmounts.96- **No dependency arrays or `useCallback`.** The hooks read the hotkey, callback, and options on every render, so inline callbacks always see current state.97- **Call the hooks directly.** A `useShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, options, app hotkeys, and the typed callback context.98- **`matchesKeyboardEvent` takes the DOM event.** In a widget's `onKeyDown`, pass `event.nativeEvent`.99- **In tests,** set `<HotkeysProvider defaultOptions={{ platform: 'mac' }}>`. It applies to hotkeys, recorders, labels, and app hotkey conflict checks.100- **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`.101102When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in React](./references/app-hotkeys.md).103104## API discovery and docs105106Signatures: `node_modules/@tanstack/react-hotkeys/dist/*.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/react/guides/<page>.md`, such as `hotkeys`, `hotkeys-provider-and-scopes`, or `app-hotkeys`. Devtools: `hotkeysDevtoolsPlugin()` from `@tanstack/react-hotkeys-devtools` in `@tanstack/react-devtools`.