@tanstack/hotkeys

Type-safe, framework-agnostic keyboard hotkey management for the browser

Source

npm

Version: 0.0.2

Version published: 8 months ago

Weekly downloads: 1.1M

Maintainers: 6

Weekly downloads

Created: 8 months ago

Source

TanStack Hotkeys

Type-safe keyboard shortcuts for the web. Template strings, parsed objects, cross-platform Mod, a singleton Hotkey Manager, and utilities for cheatsheet UIs. Built to stay SSR-friendly.

[!NOTE] TanStack Hotkeys is pre-alpha (prototyping phase). We are actively developing the library and are open to feedback and contributions.

Features

Key Bindings
- Template strings as the primary syntax: Mod+Shift+S, Control+Shift+A, Escape
- Parsed objects also supported: { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control','Shift'] }
- Type-safe Hotkey for as many valid event.key combinations as possible
Options
- keydown / keyup via eventType
- preventDefault, stopPropagation
- Conditional enabled to turn hotkeys on or off
- requireReset: trigger once until all keys are released
Cross-Platform Mod
- Mod maps to Cmd (Meta) on macOS and Ctrl on Windows/Linux
Singleton Hotkey Manager
- getHotkeyManager(), HotkeyManager.getInstance() to register global keyboard shortcuts
- Single shared listener for efficiency
Display Utilities
- formatForDisplay(hotkey) for cheatsheet UIs (symbols on Mac, labels on Windows/Linux)
- formatWithLabels, formatHotkey for flexible output
Validation & Matching
- validateHotkey, assertValidHotkey, checkHotkey for correctness validation
- matchesKeyboardEvent, createHotkeyHandler, createMultiHotkeyHandler
Sequences
- SequenceManager, createSequenceMatcher for Vim-style multi-key shortcuts (e.g. ['G','G'], ['D','I','W'])
Key State
- KeyStateTracker, getKeyStateTracker for held-key tracking
Hotkey Recorder
- HotkeyRecorder class for capturing keyboard shortcuts interactively
- Supports live preview, cancellation, and clearing during recording
React Hooks
- useHotkey – register a keyboard shortcut (global, via singleton manager)
- useHotkeySequence – detect keys pressed in order within a timeout
- useHeldKeys – reactive list of currently held keys
- useKeyHold – reactive boolean for whether a given key is held
- useHotkeyRecorder – record keyboard shortcuts interactively with live preview
Devtools
- Devtools are a core focus: visibility into all registered hotkeys, scopes, and options
- @tanstack/hotkeys-devtools and @tanstack/react-hotkeys-devtools (in active development)
Planned
- Scoping hotkeys to a DOM element or React ref
- Warn/error on conflicting shortcuts (TBD)
- Ignore hotkeys when certain inputs are focused (e.g. input, textarea)
- Focus traps and tab-order utilities

Read the docs →

[!NOTE] You may know TanStack Hotkeys by our adapter names, too!

React Hotkeys

Solid Hotkeys – needs a contributor!

Angular Hotkeys – needs a contributor!

Svelte Hotkeys – needs a contributor!

Vue Hotkeys – needs a contributor!

Quick Example

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

function Editor() {
  useHotkey(
    'Mod+S',
    (e, { hotkey }) => {
      save()
    },
    { requireReset: true },
  )

  return (
    <div>
      <button>Save</button>
      <span>{formatForDisplay('Mod+S')}</span>{' '}
      {/* e.g. "⌘S" on Mac, "Ctrl+S" on Windows */}
    </div>
  )
}

Packages

@tanstack/hotkeys – Core: parse, format, match, validate, manager, sequence, key-state
@tanstack/react-hotkeys – React: useHotkey, useHotkeySequence, useHeldKeys, useKeyHold, useHotkeyRecorder
@tanstack/hotkeys-devtools – Base devtools (in development)
@tanstack/react-hotkeys-devtools – React devtools (in development)

Get Involved

We welcome issues and pull requests!
Participate in GitHub discussions
Chat with the community on Discord
See CONTRIBUTING.md for setup instructions

Partners

We're looking for TanStack Hotkeys Partners to join our mission! Partner with us to push the boundaries of TanStack Hotkeys and build amazing things together.

LET'S CHAT