tanstack-hotkeys
TanStack Hotkeys
Overview
TanStack Hotkeys is a type-safe keyboard shortcuts library for React with template-string bindings, cross-platform Mod key abstraction (Cmd on macOS, Ctrl on Windows/Linux), and SSR-friendly utilities. It provides hooks for single hotkeys, multi-key sequences, shortcut recording, and real-time key state tracking, plus platform-aware display formatting.
When to use: Adding keyboard shortcuts to React apps, recording user-defined hotkeys, detecting held modifier keys, displaying platform-specific shortcut labels, implementing Vim-style key sequences.
When NOT to use: Non-React apps without a wrapper (core package exists but React is the primary target), complex input handling that needs full keymap management (consider a dedicated keymap library).
Quick Reference
| Pattern | API | Key Points |
|---|---|---|
| Single hotkey | useHotkey |
Mod abstracts Cmd/Ctrl; auto-prevents default on combos |
| Multi-key sequence | useHotkeySequence |
Vim-style sequences like g g; configurable timeout |
| Record shortcuts | useHotkeyRecorder |
User-defined shortcuts; start/stop/cancel recording |
| Detect key held | useKeyHold |
Boolean for specific key; optimized re-renders |
| Track all held keys | useHeldKeys |
Array of currently pressed key names |
| Track held key codes | useHeldKeyCodes |
Map of key names to physical event.code values |
| Global defaults | HotkeysProvider |
Set default options for all hooks; per-hook overrides apply |
| Format for display | formatForDisplay |
Platform-aware: macOS symbols vs Windows/Linux text |
| Scope to element | target option + ref |
Requires tabIndex on target element for focus |
| Conditional hotkeys | enabled option |
Dynamically enable/disable without unmounting |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Missing tabIndex on scoped target element |
Add tabIndex={-1} (or 0) to elements using target ref for focus |
Using Ctrl instead of Mod |
Use Mod for cross-platform; it maps to Cmd (Mac) or Ctrl (Win/Linux) |
| Assuming hotkeys fire inside inputs | ignoreInputs defaults to smart detection; set false to force firing |
| Duplicate hotkey registrations without config | Set conflictBehavior: 'replace' to override, or 'error' to catch |
Forgetting preventDefault is auto-enabled |
Modifier combos auto-prevent; set preventDefault: false to allow default |
Using keyup without requireReset |
Combine eventType: 'keyup' with requireReset: true to fire once |
Delegation
If the
tanstack-pacerskill is available, delegate throttling and debouncing tasks to it. TanStack Pacer is useful for rate-limiting hotkey callbacks. Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s tanstack-pacer -a claude-code -yIf the
tanstack-devtoolsskill is available, delegate devtools setup to it. Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s tanstack-devtools -a claude-code -y
- Keyboard shortcuts and hotkeys: Use this skill
- Throttling/debouncing hotkey callbacks: Delegate to
tanstack-pacer - DevTools integration: Delegate to
tanstack-devtools