Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a claude-code
Open on GitHub

What 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+K hotkey to CommandPalette with useHotkey
  • Wire up useHotkeyRecorder so people can set their own shortcut, then show it through formatForDisplay
  • Build a g g sequence that jumps to the top of the list using useHotkeySequence

How to install tanstack-hotkeys

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill tanstack-hotkeys -a claude-code

2Manually: put the files in place

~/.claude/skills/tanstack-hotkeys/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tanstack-hotkeys/

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

Similar skills

All skills for Frontend and UI →
tanstack-integration-best-practices DeckardGer tanstack-integration-best-practices — a skill that hands the agent rules for wiring TanStack Query, Router and Start together: loaders, SSR hydration, cache ownership. Useful once all three live in one codebase. CX Codex +1 3,100installs clerk-tanstack-patterns clerk The clerk-tanstack-patterns Claude Code skill covers Clerk authentication patterns for TanStack React Start. It activates for work with createServerFn, beforeLoad route protection, and request middleware. CX Codex +1 16,400installs tanstack-start tanstack-skills Guides agents through building full-stack React apps with TanStack Start, streaming SSR, and type-safe server functions. CX Codex +1 4,000installs tanstack-pacer tanstack-skills tanstack-pacer is a Claude Code skill for choosing utilities that control when functions run. It comes into play for debouncing, rate limits, queues, and batching. CX Codex +1 3,900installs tanstack-start-cursorrules-prompt-file PatrickJS tanstack-start-cursorrules-prompt-file — a Cursor rule for TanStack Start, a full-stack React framework with SSR, server functions and type safety. Triggers when you work on Start projects, TanStack Router routes or Vinxi config files. CX Codex +1 ★ 41,178repo stars tanstack-vue-virtual-skilld skilld-dev The tanstack-vue-virtual-skilld skill guides Vue work with @tanstack/vue-virtual, from implementing virtual lists to debugging adapter usage. It also covers window scrolling and chat feeds anchored at the end. CX Codex +1 129installs

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open