Become a Sponsor!

TanStack Keys

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 Keys is pre-alpha (prototyping phase). We are actively developing the library and are open to feedback and contributions.

Goals

• 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 and layout warnings
  • 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
• 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
• Devtools
  • Devtools are a core focus: visibility into all registered hotkeys, scopes, and options
  • @tanstack/keys-devtools and @tanstack/react-keys-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 Keys by our adapter names, too!

• React Keys
• Solid Keys – needs a contributor!
• Angular Keys – needs a contributor!
• Svelte Keys – needs a contributor!
• Vue Keys – needs a contributor!

Quick Example

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

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

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

Packages

• @tanstack/keys – Core: parse, format, match, validate, manager, sequence, key-state
• @tanstack/react-keys – React: useHotkey, useHotkeySequence, useHeldKeys, useKeyHold
• @tanstack/keys-devtools – Base devtools (in development)
• @tanstack/react-keys-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 Keys Partners to join our mission! Partner with us to push the boundaries of TanStack Keys and build amazing things together.

LET'S CHAT

Explore the TanStack Ecosystem

• TanStack Config – Tooling for JS/TS packages
• TanStack DB – Reactive sync client store
• TanStack DevTools – Unified devtools panel
• TanStack Form – Type‑safe form state
• TanStack Keys – Type‑safe keyboard shortcuts
• TanStack Query – Async state & caching
• TanStack Ranger – Range & slider primitives
• TanStack Router – Type‑safe routing, caching & URL state
• TanStack Start – Full‑stack SSR & streaming
• TanStack Store – Reactive data store
• TanStack Table – Headless datagrids
• TanStack Virtual – Virtualized rendering

… and more at TanStack.com »