React Hotkeys

Common errors

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

  cause 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

  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.
  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

  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.
  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'

  cause 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.

Warnings

• breaking 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.
  Fix: Refer to the v2.0.0 release notes for a comprehensive upgrade guide. Re-evaluate and rewrite hotkey definitions and component structures.
• breaking The `<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`.
• breaking 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.
  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']`.
• 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.
• breaking 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.
  Fix: If you need the previous behavior where repeated keydown events were processed, set the `ignoreRepeatedEventsWhenKeyHeldDown` configuration option to `false`.
• gotcha 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`.
  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.

Install

• npm install react-hotkeys npm
• yarn add react-hotkeys yarn
• pnpm add react-hotkeys pnpm

Imports

• HotKeys
  wrong:

  import HotKeys from 'react-hotkeys';

  correct:

  import { HotKeys } from 'react-hotkeys';

  HotKeys is a named export, not a default export.
• GlobalHotKeys
  wrong:

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

  correct:

  import { GlobalHotKeys } from 'react-hotkeys';

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

  import { HotKeysIgnore } from 'react-hotkeys';

  correct:

  import { IgnoreKeys } from 'react-hotkeys';

  Renamed from HotKeysIgnore to IgnoreKeys in v2.0.0-pre4 to standardize naming.
• withHotKeys
  wrong:

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

  correct:

  import { withHotKeys } from 'react-hotkeys';

  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
  wrong:

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

  correct:

  import { configure } from 'react-hotkeys';

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

Quickstart

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;