Hotkeys Guide

The useHotkey hook is the primary way to register keyboard shortcuts in React applications. It wraps the singleton HotkeyManager with automatic lifecycle management, stale-closure prevention, and React ref support.

import { useHotkey } from '@tanstack/react-hotkeys'

function App() {
  useHotkey('Mod+S', () => {
    saveDocument()
  }, {
    // override the default options here
  })
}

The callback receives the original KeyboardEvent as the first argument and a HotkeyCallbackContext as the second:

useHotkey('Mod+S', (event, context) => {
  console.log(context.hotkey)       // 'Mod+S'
  console.log(context.parsedHotkey) // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
})

You can pass a hotkey as a string or as a RawHotkey object (modifier booleans optional). Use mod for cross-platform shortcuts (Command on Mac, Control elsewhere):

useHotkey('Mod+S', () => save())
useHotkey({ key: 'S', mod: true }, () => save())           // Same as above
useHotkey({ key: 'Escape' }, () => closeModal())
useHotkey({ key: 'S', ctrl: true, shift: true }, () => saveAs())
useHotkey({ key: 'S', mod: true, shift: true }, () => saveAs())

When you register a hotkey without passing options, or when you omit specific options, the following defaults apply:

useHotkey('Mod+S', callback, {
  enabled: true,
  preventDefault: true,
  stopPropagation: true,
  eventType: 'keydown',
  requireReset: false,
  ignoreInputs: undefined, // smart default: false for Mod+S, true for single keys
  target: document,
  platform: undefined, // auto-detected
  conflictBehavior: 'warn',
})

Most hotkey registrations are intended to override default browser behavior—such as using Mod+S to save a document instead of showing the browser’s "Save Page" dialog. To make this easy and consistent, the library sets preventDefault and stopPropagation to true by default, ensuring your hotkey handlers take precedence and reducing the amount of repetitive boilerplate code required.

The ignoreInputs option is designed to strike a balance between accessibility and usability. By default, hotkeys involving Ctrl/Meta modifiers (like Mod+S) and the Escape key are allowed to fire even when the focus is inside input elements (such as text fields or text areas), and when focused on button-type inputs (type="button", "submit", or "reset"). This allows shortcuts like save or close to work wherever the user is focused. On the other hand, single key shortcuts or those using only Shift/Alt are ignored within non-button inputs to prevent interference with normal typing.

When you attempt to register a hotkey that is already registered (possibly in another part of your app), the library logs a warning by default using the conflictBehavior: 'warn' setting. This helps you catch accidental duplicate bindings during development so they can be resolved before reaching production.

You can change the default options for all useHotkey calls in your app by wrapping your component tree with HotkeysProvider. Per-hook options will override the provider defaults.

import { HotkeysProvider } from '@tanstack/react-hotkeys'

<HotkeysProvider
  defaultOptions={{
    hotkey: { preventDefault: false, ignoreInputs: false },
  }}
>
  <App />
</HotkeysProvider>

Controls whether the hotkey is active. Defaults to true.

const [isEditing, setIsEditing] = useState(false)

// Only active when editing
useHotkey('Mod+S', () => save(), { enabled: isEditing })

Automatically calls event.preventDefault() when the hotkey fires. Defaults to true.

// Browser default is prevented by default
useHotkey('Mod+S', () => save())

// Opt out when you want the browser's default behavior
useHotkey('Mod+S', () => save(), { preventDefault: false })

Calls event.stopPropagation() when the hotkey fires. Defaults to true.

// Event propagation is stopped by default
useHotkey('Escape', () => closeModal())

// Opt out when you need the event to bubble
useHotkey('Escape', () => closeModal(), { stopPropagation: false })

Whether to listen on keydown (default) or keyup.

// Fire when the key is released
useHotkey('Shift', () => deactivateMode(), { eventType: 'keyup' })

When true, the hotkey will only fire once per key press. The key must be released and pressed again to fire again. Defaults to false.

// Only fires once per Escape press, not on key repeat
useHotkey('Escape', () => closePanel(), { requireReset: true })

When true, the hotkey will not fire when the user is focused on a text input, textarea, select, or contentEditable element. Button-type inputs (type="button", "submit", "reset") are not ignored, so shortcuts like Mod+S work when the user has tabbed to a form button. When unset, a smart default applies: Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.

// Single key - ignored in inputs by default (smart default)
useHotkey('K', () => openSearch())

// Mod+S and Escape - fire in inputs by default (smart default)
useHotkey('Mod+S', () => save())
useHotkey('Escape', () => closeDialog())

// Override: force a single key to fire in inputs
useHotkey('Enter', () => submit(), { ignoreInputs: false })

Set ignoreInputs: false or true explicitly to override the smart default.

The DOM element to attach the event listener to. Defaults to document. Can be a DOM element, document, window, or a React ref.

import { useRef } from 'react'

function Panel() {
  const panelRef = useRef<HTMLDivElement>(null)

  // Only listens for events on this specific element
  useHotkey('Escape', () => closePanel(), { target: panelRef })

  return (
    <div ref={panelRef} tabIndex={0}>
      <p>Panel content</p>
    </div>
  )
}

Controls what happens when you register a hotkey that's already registered. Options:

• 'warn' (default) - Logs a warning but allows the registration
• 'error' - Throws an error
• 'replace' - Replaces the existing registration
• 'allow' - Allows multiple registrations silently

useHotkey('Mod+S', () => save(), { conflictBehavior: 'replace' })

Override the auto-detected platform. Useful for testing or for applications that need to force a specific platform behavior.

useHotkey('Mod+S', () => save(), { platform: 'mac' })

The useHotkey hook automatically syncs the callback on every render, so you never need to worry about stale closures:

function Counter() {
  const [count, setCount] = useState(0)

  // This callback always has access to the latest `count` value
  useHotkey('Mod+Shift+C', () => {
    console.log('Current count:', count)
  })

  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>
}

The hook automatically unregisters the hotkey when the component unmounts:

function TemporaryPanel() {
  // Automatically cleaned up when this component unmounts
  useHotkey('Escape', () => closePanel())

  return <div>Panel content</div>
}

Under the hood, useHotkey uses the singleton HotkeyManager. You can also access the manager directly if needed:

import { getHotkeyManager } from '@tanstack/react-hotkeys'

const manager = getHotkeyManager()

// Check if a hotkey is registered
manager.isRegistered('Mod+S')

// Get total number of registrations
manager.getRegistrationCount()

The manager attaches event listeners per target element, so only elements that have registered hotkeys receive listeners. This is more efficient than a single global listener.