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-pacer skill 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 -y

If the tanstack-devtools skill 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

References

• React hooks and configuration
• Sequences and recording
• Formatting and display