Registry / web-framework / react-hotkeys

react-hotkeys

library2.0.0jsnpmunverified

React Hotkeys is a declarative library for managing keyboard shortcuts and focus within React applications. The current stable version is 2.0.0, representing a complete internal rewrite that removed the dependency on Mousetrap and now directly leverages React's SyntheticEvent system. This change significantly improved integration and predictable behavior within the React ecosystem. The library offers both component-based APIs (`<HotKeys>`, `<GlobalHotKeys>`, `<IgnoreKeys>`) and Higher-Order Components (`withHotKeys`, `withIgnoreKeys`) to define and handle hotkeys. Key features include support for standard browser key names and Mousetrap-like syntax, the ability to define global or context-specific hotkeys, dynamic hotkey configuration at runtime, and tools to display available shortcuts to users. It ships with comprehensive TypeScript types and is optimized for performance in large applications, with over 2000 automated tests ensuring reliability. Release cadence tends to be active during major version development, followed by maintenance releases.

web-framework

npm install react-hotkeys

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-HOTKEYS

react-hotkeys

web-frameworkjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HotKeys

✓ import { HotKeys } from 'react-hotkeys';

✗ import HotKeys from 'react-hotkeys';

HotKeys is a named export, not a default export.

GlobalHotKeys

✓ import { GlobalHotKeys } from 'react-hotkeys';

✗ import { HotKeys } from 'react-hotkeys/global';

GlobalHotKeys is for application-wide hotkeys and is a named export from the main package.

IgnoreKeys

✓ import { IgnoreKeys } from 'react-hotkeys';

✗ import { HotKeysIgnore } from 'react-hotkeys';

Renamed from HotKeysIgnore to IgnoreKeys in v2.0.0-pre4 to standardize naming.

withHotKeys

✓ import { withHotKeys } from 'react-hotkeys';

✗ const withHotKeys = require('react-hotkeys').withHotKeys;

While CommonJS `require()` can technically access named exports, the library is primarily designed for ESM usage with named imports, especially with TypeScript, for better tree-shaking and module resolution.

configure

✓ import { configure } from 'react-hotkeys';

✗ import { HotKeys } from 'react-hotkeys'; HotKeys.configure({...});

Global configuration is managed via the `configure` named export, not directly on the HotKeys component or instance.

This quickstart demonstrates defining a global key map and then applying specific handlers to a nested component, `MyNode`. It showcases how to bind multiple key combinations to a single action and includes basic React functional component usage with `useCallback` for handler stability. The root `<HotKeys>` component defines the context for all children.

import { HotKeys } from "react-hotkeys"; import React, { useCallback } from 'react'; const keyMap = { SNAP_LEFT: "command+left", DELETE_NODE: ["del", "backspace"] }; const MyNode = () => { const deleteNode = useCallback(() => { console.log('Delete node action triggered!'); // Implement your node deletion logic here }, []); const handlers = { DELETE_NODE: deleteNode }; return ( <HotKeys handlers={handlers}> <div style={{ padding: '20px', border: '1px solid #ccc', margin: '10px' }}> Node contents. Press 'Del' or 'Backspace' to delete. </div> </HotKeys> ); }; const App = () => { return ( <HotKeys keyMap={keyMap}> <div style={{ fontFamily: 'sans-serif' }}> <h1>React Hotkeys Demo</h1> <p>Focus this area and try hotkeys. Command+Left is global, Del/Backspace is on MyNode.</p> <MyNode /> <MyNode /> <input type="text" placeholder="Type here to test input ignore" style={{ marginTop: '20px' }} /> </div> </HotKeys> ); }; export default App;

Debug

Known issues

breakingVersion 2.0.0 represents a complete internal rewrite, removing the Mousetrap dependency. Applications upgrading from v1.* will require significant changes to adapt to the new API and event handling system. The `__mousetrap__` property is no longer available.

fix

Refer to the v2.0.0 release notes for a comprehensive upgrade guide. Re-evaluate and rewrite hotkey definitions and component structures.

affects: >=2.0.0

breakingThe `<HotKeysIgnore />` component has been renamed to `<IgnoreKeys />`, and the `withHotKeysIgnore` HOC has been renamed to `withIgnoreKeys` for consistent naming conventions.

fix

Update all instances of `<HotKeysIgnore />` to `<IgnoreKeys />` and `withHotKeysIgnore` to `withIgnoreKeys`.

affects: >=2.0.0-pre4

breakingThe keys `Delete` and `Backspace` (and the variant `del`) are no longer treated as aliases for one another. If you relied on this aliasing, you must now explicitly bind handlers to both keys.

fix

Ensure your `keyMap` and `handlers` explicitly list both `del` (or `delete`) and `backspace` if you want both keys to trigger the same action, e.g., `DELETE_NODE: ['del', 'backspace']`.

affects: >=2.0.0-pre5

breaking`react-hotkeys` now ignores key combination submatches by default. This change addresses issues where shorter, context-dependent key combinations would hide longer, global ones, potentially preventing them from ever being triggered.

fix

If you require the old behavior where submatches were not ignored, you may need to adjust your key map structure or configuration. Review your hotkey priorities to ensure desired behavior.

affects: >=2.0.0-pre7

breakingRepeated `keydown` events that occur when a key is held down are now ignored by default. This prevents a single long press from triggering an action multiple times.

fix

If you need the previous behavior where repeated keydown events were processed, set the `ignoreRepeatedEventsWhenKeyHeldDown` configuration option to `false`.

affects: >=2.0.0-pre8

gotchaWhen the `Cmd` (Meta) key is pressed down, the `allowCombinationSubmatches` configuration option is ignored, and submatches are always allowed. This is a specific fix for navigating between `Cmd`+number hotkeys without releasing `Cmd`.

fix

Be aware that `Cmd` key combinations might behave differently regarding submatches than other modifier keys. Plan your `Cmd` hotkeys accordingly, and test common user flows.

affects: >=2.0.0-pre9

Errors

Common errors & fixes

Legacy context API has been detected within a strict-mode tree

Using an older, deprecated way of accessing React context within a StrictMode component tree, leading to warnings.

fix

This issue was specifically addressed in `react-hotkeys` v2.0.0-pre6. Ensure you are on the latest v2.x version to avoid this warning. The library is now compatible with React StrictMode.

HotKeys not working for form fields/inputs

Hotkeys might be unintentionally blocked or not registering within standard HTML form elements (`input`, `textarea`, `select`), as `react-hotkeys` often ignores events from these elements by default.

fix

Ensure that the `HotKeys` component is correctly positioned in the component tree. Check the `allowEventPropagation` and `ignoreEventsCondition` configuration options, and review the 'What it actually means to ignore an event' documentation to customize this behavior.

Global hotkeys throwing errors after dom changes

Dynamic DOM manipulation or unmounting/remounting components might interfere with how global hotkeys register and unregister their listeners, causing stale references or unexpected errors.

fix

This was a known bug addressed in `react-hotkeys` v2.0.0-pre6. Ensure you are on the latest v2.x version to benefit from these fixes. If the issue persists, review how your components unmount and remount, and whether the `HotKeys` provider tree remains stable.

Property 'ref' does not exist on type 'IntrinsicAttributes & HotKeysProps'

TypeScript error indicating an incorrect type definition for the `ref` prop when used directly with `HotKeys` components.

fix

This was a known TypeScript type bug addressed in `react-hotkeys` v2.0.0-pre6. Ensure your TypeScript version and `react-hotkeys` version (>=2.0.0-pre6) are compatible. Use the `innerRef` prop instead of `ref` as specified by the library for accessing the underlying DOM node.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency for any React application using the library.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/greena13/react-hotkeys ↗

packagehttps://www.npmjs.com/package/react-hotkeys ↗