{"id":15189,"library":"react-hotkeys","title":"React Hotkeys","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/greena13/react-hotkeys","tags":["javascript","react-component","hotkeys","focus","react","typescript"],"install":[{"cmd":"npm install react-hotkeys","lang":"bash","label":"npm"},{"cmd":"yarn add react-hotkeys","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-hotkeys","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for any React application using the library.","package":"react","optional":false}],"imports":[{"note":"HotKeys is a named export, not a default export.","wrong":"import HotKeys from 'react-hotkeys';","symbol":"HotKeys","correct":"import { HotKeys } from 'react-hotkeys';"},{"note":"GlobalHotKeys is for application-wide hotkeys and is a named export from the main package.","wrong":"import { HotKeys } from 'react-hotkeys/global';","symbol":"GlobalHotKeys","correct":"import { GlobalHotKeys } from 'react-hotkeys';"},{"note":"Renamed from HotKeysIgnore to IgnoreKeys in v2.0.0-pre4 to standardize naming.","wrong":"import { HotKeysIgnore } from 'react-hotkeys';","symbol":"IgnoreKeys","correct":"import { IgnoreKeys } from 'react-hotkeys';"},{"note":"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.","wrong":"const withHotKeys = require('react-hotkeys').withHotKeys;","symbol":"withHotKeys","correct":"import { withHotKeys } from 'react-hotkeys';"},{"note":"Global configuration is managed via the `configure` named export, not directly on the HotKeys component or instance.","wrong":"import { HotKeys } from 'react-hotkeys'; HotKeys.configure({...});","symbol":"configure","correct":"import { configure } from 'react-hotkeys';"}],"quickstart":{"code":"import { HotKeys } from \"react-hotkeys\";\nimport React, { useCallback } from 'react';\n\nconst keyMap = {\n  SNAP_LEFT: \"command+left\",\n  DELETE_NODE: [\"del\", \"backspace\"]\n};\n\nconst MyNode = () => {\n  const deleteNode = useCallback(() => {\n    console.log('Delete node action triggered!');\n    // Implement your node deletion logic here\n  }, []);\n\n  const handlers = {\n    DELETE_NODE: deleteNode\n  };\n\n  return (\n    <HotKeys handlers={handlers}>\n      <div style={{ padding: '20px', border: '1px solid #ccc', margin: '10px' }}>\n        Node contents. Press 'Del' or 'Backspace' to delete.\n      </div>\n    </HotKeys>\n  );\n};\n\nconst App = () => {\n  return (\n    <HotKeys keyMap={keyMap}>\n      <div style={{ fontFamily: 'sans-serif' }}>\n        <h1>React Hotkeys Demo</h1>\n        <p>Focus this area and try hotkeys. Command+Left is global, Del/Backspace is on MyNode.</p>\n        <MyNode />\n        <MyNode />\n        <input type=\"text\" placeholder=\"Type here to test input ignore\" style={{ marginTop: '20px' }} />\n      </div>\n    </HotKeys>\n  );\n};\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Refer to the v2.0.0 release notes for a comprehensive upgrade guide. Re-evaluate and rewrite hotkey definitions and component structures.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update all instances of `<HotKeysIgnore />` to `<IgnoreKeys />` and `withHotKeysIgnore` to `withIgnoreKeys`.","message":"The `<HotKeysIgnore />` component has been renamed to `<IgnoreKeys />`, and the `withHotKeysIgnore` HOC has been renamed to `withIgnoreKeys` for consistent naming conventions.","severity":"breaking","affected_versions":">=2.0.0-pre4"},{"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']`.","message":"The 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.","severity":"breaking","affected_versions":">=2.0.0-pre5"},{"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.","message":"`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.","severity":"breaking","affected_versions":">=2.0.0-pre7"},{"fix":"If you need the previous behavior where repeated keydown events were processed, set the `ignoreRepeatedEventsWhenKeyHeldDown` configuration option to `false`.","message":"Repeated `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.","severity":"breaking","affected_versions":">=2.0.0-pre8"},{"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.","message":"When 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`.","severity":"gotcha","affected_versions":">=2.0.0-pre9"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Using an older, deprecated way of accessing React context within a StrictMode component tree, leading to warnings.","error":"Legacy context API has been detected within a strict-mode tree"},{"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.","cause":"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.","error":"HotKeys not working for form fields/inputs"},{"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.","cause":"Dynamic DOM manipulation or unmounting/remounting components might interfere with how global hotkeys register and unregister their listeners, causing stale references or unexpected errors.","error":"Global hotkeys throwing errors after dom changes"},{"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.","cause":"TypeScript error indicating an incorrect type definition for the `ref` prop when used directly with `HotKeys` components.","error":"Property 'ref' does not exist on type 'IntrinsicAttributes & HotKeysProps'"}],"ecosystem":"npm"}