TanStack Hotkeys: Type-Safe Keyboard Shortcuts for React

Keyboard shortcuts are one of the fastest ways to make an application feel professional. When done right, they make navigation faster, workflows smoother, and power users noticeably happier. When done poorly, they create conflicts, break across operating systems, and become difficult to maintain.

TanStack Hotkeys exists to solve that complexity.

It is a type-safe, cross-platform, framework-agnostic library built specifically for managing keyboard shortcuts in modern applications. Instead of manually wiring keydown listeners and handling edge cases yourself, TanStack Hotkeys gives you a structured, predictable system for defining, scoping, and debugging hotkeys.

The real challenge with keyboard shortcuts is not detecting key presses. It is handling operating system differences, managing modifier keys correctly, avoiding input conflicts, supporting sequences, and keeping everything maintainable as your app grows. TanStack Hotkeys addresses all of these problems at the architectural level.

In this guide, you will learn how to define basic shortcuts, scope them to specific components, build multi-key sequences, track held keys, and even let users record their own shortcuts. You will also see how its type-safety and DevTools support make development significantly easier.

By the end, you will understand not just how to add hotkeys, but how to design a scalable hotkey system that feels native and reliable.

Getting started: an introduction to the core concepts

Before jumping into the code, understanding what makes TanStack Hotkeys so special is essential. At its core, the library is built to be "headless," meaning it provides the logic and state management for hotkeys without imposing any specific UI. This gives you complete freedom to build your interface however you see fit.

The library is currently in alpha but is already packed with features that address common pain points:

Type-safety: With first-class TypeScript support, you get autocompletion and compile-time checks for your hotkey definitions, drastically reducing the chance of typos and runtime errors.

Cross-platform by default: The library abstracts away the differences between operating systems. You can define a shortcut once, and it will automatically work for users on macOS, Windows, and Linux.

Framework agnostic: While this article uses the React adapter (@tanstack/react-hotkeys), the core logic is available in a vanilla JavaScript package (@tanstack/hotkeys), with adapters for other frameworks like Solid, Vue, and Svelte on the horizon.

Advanced features: It goes beyond simple key presses, offering support for key sequences (like Vim-style commands), hotkey recording for user customization, and fine-grained state tracking.

Excellent developer experience: True to the TanStack ecosystem, it comes with dedicated DevTools for easy debugging and a simple, intuitive API.

For this tutorial, working within a React application requires installing the necessary package:

npm install @tanstack/react-hotkeys

Or with yarn:

yarn add @tanstack/react-hotkeys

Or with pnpm:

pnpm add @tanstack/react-hotkeys

With the package installed, implementing the first hotkey becomes possible.

The core: understanding the useHotkey hook

The primary workhorse of the React adapter is the useHotkey hook. This hook is incredibly simple to use yet powerful enough to handle most of your hotkey needs. It takes up to three arguments: the hotkey definition, a callback function to execute, and an optional configuration object.

Breaking down its usage with a classic example: opening a command palette with Cmd+K or Ctrl+K:

import { useHotkey } from "@tanstack/react-hotkeys";
import { useState } from "react";

function HotkeyPage() {
  const [paletteOpen, setPaletteOpen] = useState(false);

  useHotkey("Mod+K", (event, context) => {
    console.log(`Hotkey pressed: ${context.hotkey}`);
    setPaletteOpen((open) => !open);
  });

  return (
    <div>
      {paletteOpen && <CommandPalette />}
      <p>Press Mod+K to toggle the command palette.</p>
    </div>
  );
}

In this example, useHotkey is called with two arguments: the string 'Mod+K' (which defines the keyboard shortcut) and a callback function that toggles the paletteOpen state, which in turn would show or hide a command palette component.

It's that simple. The hook handles listening for the keydown events and executing your logic when the specific combination is pressed.

The power of type-safety in hotkey definitions

One of the standout features of TanStack Hotkeys is its deep integration with TypeScript. The hotkey definition string is not just any string; it's a type-safe string literal. This means your code editor will provide autocompletion for all possible keys and modifiers, and TypeScript will throw an error if you try to use an invalid combination.

This developer experience feature is a game-changer. It prevents common mistakes like misspelling a key or trying to use a non-existent key. The library knows all standard modifier keys (Shift, Alt, Control, Meta) and all standard character and function keys.

Mastering cross-platform hotkeys with Mod

You might have noticed the use of Mod in the example instead of Cmd or Ctrl. This is a crucial feature for creating a seamless cross-platform experience. The Mod key is a special alias provided by TanStack Hotkeys that automatically resolves to the primary modifier key for the user's operating system.

On macOS, Mod resolves to the Command (Cmd) key. On Windows and Linux, Mod resolves to the Control (Ctrl) key.

By using Mod+K, you are defining a single hotkey that works intuitively for all your users, regardless of their OS. If you were to use 'Meta+K' (where Meta is the Command key) it would only work on macOS. Similarly, 'Control+K' would feel unnatural for a Mac user who is accustomed to using the Command key for primary actions. The Mod alias solves this problem elegantly.

Flexible hotkey definitions: string vs. object

While the string syntax is concise and great for most cases, TanStack Hotkeys also provides a more verbose object syntax for defining shortcuts. This can be useful for programmatic or more complex definitions.

The hotkey 'Mod+K' can also be expressed as an object:

useHotkey(
  {
    key: "K",
    mod: true, // This enables the cross-platform Mod key
    shift: false, // Explicitly not requiring Shift
    alt: false, // Explicitly not requiring Alt
  },
  () => {
    // ... callback logic
  },
);

This object syntax gives you explicit control over every modifier key. You can see how mod: true corresponds to using the Mod alias in the string syntax. Both definitions are functionally identical, so you can choose the one that best fits your coding style or requirements.

Advanced hotkey configurations and options

The useHotkey hook's third argument is an options object that allows you to fine-tune the behavior of your hotkey. This is where you can handle more advanced scenarios and edge cases.

Exploring some of the most useful options:

enabled: boolean

This option allows you to programmatically enable or disable a hotkey. It defaults to true. You can tie this to a piece of state to control when a shortcut is active.

Use case: You might want to disable global hotkeys when a modal dialog is open to prevent unintended actions in the background.

const [isModalOpen, setIsModalOpen] = useState(false);

useHotkey("Mod+S", () => saveDocument(), {
  enabled: !isModalOpen,
});

eventType: 'keydown' or 'keyup'

By default, the hotkey callback fires on the keydown event. You can change this to keyup if you need the action to trigger when the user releases the keys.

Use case: Implementing a "push-to-talk" feature where the microphone is active only while a key is held down. You would use keydown to start and keyup to stop.

ignoreInputs: boolean

A common requirement is to prevent hotkeys from firing when the user is typing in an input field, textarea, or a content-editable element. By default, TanStack Hotkeys smartly handles this (it defaults to true for single keys but false for combinations with Mod), but you can explicitly control this behavior.

Use case: If you have a hotkey like S to save, you don't want it to trigger every time a user types the letter 's' in a search bar. Setting ignoreInputs: true (which is often the default) prevents this.

target: HTMLElement or React.RefObject

This powerful option allows you to scope a hotkey to a specific DOM element. By default, hotkeys are global and listen on the document. By providing a ref to an element, the hotkey will only be active when that element or one of its children is focused.

Use case: You could have a data grid component where the arrow keys are used for navigation, but only when the grid itself is focused.

const gridRef = useRef(null);

useHotkey("ArrowUp", () => navigateUp(), {
  target: gridRef,
});

return (
  <div ref={gridRef} tabIndex={-1}>
    ...Your Grid...
  </div>
);

Working with key sequences: the useHotkeySequence hook

Many advanced applications, particularly code editors like VS Code, utilize key sequences (multiple key presses in a row) to trigger actions. A classic example comes from the Vim editor, where pressing g followed by another g (gg) moves the cursor to the top of the file.

TanStack Hotkeys makes this easy with the useHotkeySequence hook.

The API is very similar to useHotkey, but instead of a string, you provide an array of keys for the sequence:

import { useHotkeySequence } from "@tanstack/react-hotkeys";

// Example: Jump to top of a list with 'g' then 'g'
useHotkeySequence(
  ["G", "G"],
  () => {
    console.log("Jumped to top!");
    // Logic to scroll to the top
  },
  { timeout: 1000 },
);

In this code, if the user presses G and then presses G again within 1000 milliseconds (1 second), the callback function will be executed. The timeout option is crucial for defining how much time the user has between key presses for it to be considered a valid sequence.

This opens up a whole new realm of possibilities for creating powerful, layered keyboard shortcuts without cluttering the main modifier key combinations.

Tracking key states: useKeyHold and useHeldKeys

Sometimes, you don't need to trigger an action, but you do need to know if a specific key is currently being held down. This is useful for dynamically changing the UI or modifying the behavior of other actions, like holding Shift to select multiple items in a list.

The library provides two simple hooks for this: useKeyHold(key) (takes a single key as an argument and returns a boolean value indicating whether that key is currently pressed) and useHeldKeys() (takes no arguments and returns an array of strings, listing all keys that are currently held down).

import { useKeyHold, useHeldKeys } from "@tanstack/react-hotkeys";

function KeyStateTracker() {
  const isShiftHeld = useKeyHold("Shift");
  const heldKeys = useHeldKeys();

  return (
    <div>
      <p>Is Shift Held? {isShiftHeld ? "Yes" : "No"}</p>
      <p>All Held Keys: {heldKeys.join(", ") || "None"}</p>
    </div>
  );
}

These hooks are incredibly efficient as they tap into a global state manager, ensuring your component re-renders only when the relevant key states change.

Building interactive features: the useHotkeyRecorder hook

Perhaps one of the most impressive features of TanStack Hotkeys is the useHotkeyRecorder hook. This helper hook provides all the necessary logic to build a UI that allows users to record and set their own custom keyboard shortcuts. This is a hallmark of professional desktop applications and is now incredibly simple to implement on the web.

The hook returns an object with state and functions to manage the recording process.

Here's a breakdown of how you might use it:

import { useHotkeyRecorder } from "@tanstack/react-hotkeys";
import { useState } from "react";

function ShortcutCustomizer() {
  const [paletteHotkey, setPaletteHotkey] = useState("Mod+K");

  const { isRecording, startRecording, cancelRecording } = useHotkeyRecorder({
    onRecord: (hotkey) => {
      console.log("New hotkey recorded:", hotkey);
      setPaletteHotkey(hotkey);
    },
  });

  return (
    <div>
      <span>Shortcut for Command Palette: {paletteHotkey}</span>
      <button onClick={isRecording ? undefined : startRecording}>
        {isRecording ? `Recording... Press keys...` : "Change Shortcut"}
      </button>
    </div>
  );
}

This hook abstracts away all the complexity of listening for a key combination and parsing it into the correct format. The isRecording boolean lets you change your UI to give the user feedback, and the startRecording function is all you need to trigger the process.

Polishing the UI: formatting and utility functions

To help you display hotkeys in your UI in a clean and platform-appropriate way, the library exports a couple of helpful utility functions: formatForDisplay(hotkey) (takes a hotkey string like 'Mod+K' and formats it for display using platform-specific symbols; on macOS, it would return ⌘K) and formatWithLabels(hotkey) (does the same but uses text labels instead of symbols; on macOS, it would return Cmd+K).

These small utilities save you the effort of writing OS-detection logic and ensure your UI looks professional and consistent with the user's native environment.

Debugging with TanStack Devtools

As with other TanStack libraries, the Hotkeys library integrates seamlessly with TanStack DevTools. This provides a powerful debugging panel right in your application during development.

The DevTools allow you to see a list of all active hotkeys and sequences in your application, inspect the detailed configuration of each hotkey (including its options and target element), view the current state (such as how many times a hotkey has been triggered), manually trigger a hotkey's callback function directly from the DevTools, and see which keys are currently being held down in real-time.

This is an invaluable tool for understanding and debugging complex hotkey interactions, especially in a large application with many registered shortcuts.

Final thoughts

Keyboard shortcuts look simple on the surface. Underneath, they involve platform quirks, modifier rules, focus management, and subtle UX decisions. TanStack Hotkeys turns that complexity into something manageable.

Instead of scattered event listeners and ad hoc logic, you get a consistent API. Instead of guessing whether a shortcut works on macOS and Windows, you rely on built-in cross-platform abstractions like Mod. Instead of debugging invisible key conflicts, you use DevTools to inspect and trigger shortcuts directly.

That combination is what makes the library stand out. It improves both developer experience and end-user experience at the same time.

In this article, you explored the core useHotkey hook, advanced configuration options, key sequences, key state tracking, and customizable shortcuts with useHotkeyRecorder. Together, these features make it possible to build applications that feel fast, polished, and thoughtfully engineered.

If your application relies on productivity, navigation speed, or power-user workflows, keyboard shortcuts are not optional. They are a competitive advantage.

TanStack Hotkeys gives you the foundation to implement them correctly, scale them confidently, and maintain them without friction.

Got an article suggestion? Let us know

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.