react-hotkeys-hook

react-hotkeys-hook is a small, dependency-free React hook that lets you bind keyboard shortcuts to component logic in a declarative way. A single useHotkeys(keys, callback) call registers combinations like ctrl+k or shift+a, handles modifier keys across platforms, and cleans itself up on unmount.

Beyond the basic hook it ships scopes for grouping and toggling shortcuts, focus-trapping so a hotkey only fires when a specific element is focused, form-aware filtering that prevents accidental triggers while typing, and a useRecordHotkeys hook for capturing user-defined key bindings. It is written in TypeScript and works with any React 16.8+ application.

What You Get

• The useHotkeys(keys, callback, options, deps) hook for declarative shortcut binding
• A HotkeysProvider plus useHotkeysContext for grouping shortcuts into activatable scopes
• Focus trapping, form-tag filtering, and contentEditable handling out of the box
• useRecordHotkeys for capturing user-defined key combinations and isHotkeyPressed for imperative checks
• First-class TypeScript types and a documented options API

Common Use Cases

• Adding application-wide shortcuts like a command palette (ctrl+k) or save (mod+s)
• Scoping shortcuts to specific views or modals so they do not collide
• Building a settings UI that lets users record and remap their own key bindings
• Restricting a shortcut to a focused element such as an editable region or list item

Under The Hood

Architecture - The library is a small, focused set of modules under packages/react-hotkeys-hook/src/lib. useHotkeys.ts is the core hook: it normalizes the keys/options/deps arguments, memoizes the callback and options (via useDeepEqualMemo), keeps mutable function options in refs to avoid re-registering listeners, and attaches a keydown/keyup handler that matches events against parsed hotkeys. parseHotkeys.ts turns strings like ctrl+k into a normalized Hotkey shape and maps physical key codes to canonical names (including macOS detection for the mod alias). validators.ts centralizes the predicates that decide whether a hotkey should fire (enabled, scope active, tag allowed, event matches). HotkeysProvider.tsx supplies scope state through context, isHotkeyPressed.ts tracks currently-pressed keys as module-level state for imperative checks, and useRecordHotkeys.ts captures live key presses for remapping UIs. index.ts re-exports the public surface.

Tech Stack - Written almost entirely in TypeScript (99%), distributed as an ESM package with sideEffects: false for tree-shaking. React and react-dom are peer dependencies (>=16.8.0) and it ships with zero runtime dependencies. The build uses Vite with vite-plugin-dts for type emission, the repo is an npm-workspaces monorepo (the library plus a documentation site), tests run on Vitest with Testing Library and jsdom, and Biome handles formatting and linting.

Code Quality - The src/test directory holds five test suites covering the hook, context/provider, recording, and pressed-key tracking against a jsdom environment. Types are declared explicitly in types.ts (e.g. Keys, Options, HotkeysEvent, FormTags) and the public API is fully typed. The core hook contains explanatory comments around its trickiest concern - keeping callbacks and options current in refs without re-registering event listeners - which shows deliberate handling of a common React footgun.

API Design - The public surface is intentionally tiny and ergonomic: useHotkeys(keys, callback, options?, deps?) covers the common case in one line, mirroring the familiar useCallback dependency-array convention so React developers need almost no ramp-up. Naming is consistent (useHotkeysContext, useRecordHotkeys, isHotkeyPressed), advanced behavior is opt-in through a documented Options object, and the project backs it with a dedicated documentation site and live examples, keeping the barrier to getting started very low.