tanstack-hotkeys — Claude Code skill: React hotkeys, install guide
An agent skill for adding keyboard shortcuts to React with TanStack Hotkeys: single bindings, key sequences, user-recorded shortcuts.
MIT 179 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a claude-codeWhat tanstack-hotkeys does
This skill hands the agent a working reference for TanStack Hotkeys. useHotkey binds one combination, useHotkeySequence handles Vim-style chains such as g g, and useHotkeyRecorder lets users capture their own shortcut. Two hooks report live key state: useKeyHold watches a single key, useHeldKeys returns everything pressed right now. Shared options live in HotkeysProvider, and formatForDisplay produces labels that fit the platform.
Type Mod instead of Ctrl and the library resolves it to Cmd on macOS or Ctrl on Windows and Linux. Modifier combos suppress the browser default on their own. Scope a hook to an element with target and forget tabIndex, and nothing fires, because that element cannot take focus. Pair eventType: 'keyup' with requireReset: true or the handler keeps repeating.
Throttling callbacks belongs to tanstack-pacer, DevTools setup to tanstack-devtools; the skill delegates when either is present and otherwise says how to add it from the same repository. React is the main target — other frameworks need a wrapper.
What it helps with
- bind a single hotkey to an action in a React component
- add a Vim-style key sequence like
g g - let users record their own shortcut
- print shortcut labels that match macOS or Windows
- detect a held modifier key with few re-renders
Example prompts for the agent
- Add a
Mod+Khotkey toCommandPalettewithuseHotkey - Wire up
useHotkeyRecorderso people can set their own shortcut, then show it throughformatForDisplay - Build a
g gsequence that jumps to the top of the list usinguseHotkeySequence
How to install tanstack-hotkeys
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a claude-code2Manually: put the files in place
~/.claude/skills/tanstack-hotkeys/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tanstack-hotkeys/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a codex2Manually: put the files in place
.agents/skills/tanstack-hotkeys/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a cursor2Manually: put the files in place
.cursor/skills/tanstack-hotkeys/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/tanstack-hotkeys2Manually: put the files in place
.github/skills/tanstack-hotkeys/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/tanstack-hotkeysManually: put the files in place
.devin/skills/tanstack-hotkeys/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tanstack-hotkeys
How do I install tanstack-hotkeys in Claude Code?
Run npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a claude-code. The skill file lands at ~/.claude/skills/tanstack-hotkeys/SKILL.md.
What does tanstack-hotkeys do?
It gives the agent a reference for the TanStack Hotkeys hooks: single combinations, key sequences, shortcut recording, held-key tracking and platform-aware labels.
Does tanstack-hotkeys work outside React?
React is the primary target and the skill is written around its hooks. A core package exists, but non-React apps need a wrapper.
Source text
SKILL.md · MIT
---
name: tanstack-hotkeys
description: 'TanStack Hotkeys for type-safe keyboard shortcuts with React hooks. Use when adding keyboard shortcuts, hotkey sequences, shortcut recording, key hold detection, or platform-aware shortcut display. Use for hotkeys, keyboard-shortcuts, shortcuts, key-binding, Mod key, hotkey-recorder, key-sequences.'
license: MIT
metadata:
author: oakoss
version: '1.0'
source: 'https://tanstack.com/hotkeys/latest'
user-invocable: false
---
# 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](references/react-hooks.md)
- [Sequences and recording](references/sequences-and-recording.md)
- [Formatting and display](references/formatting-and-display.md)
© oakoss · MIT · oakoss/agent-skills