Declarative Keyboard Shortcuts for React

Common errors

• TypeError: Cannot read properties of undefined (reading 'shortcuts')

  cause This error occurs when a `<Shortcuts>` component attempts to access the `shortcuts` object from the React context, but a parent component has not properly provided it using the legacy `getChildContext` and `childContextTypes` pattern, or the context mechanism has broken due to React version incompatibility.
  fix Ensure that a parent component (`App` in the quickstart) implements both `getChildContext` to return the `shortcutManager` and `childContextTypes` to declare its type (`PropTypes.object.isRequired`). Verify that your React version is compatible (React 16 or earlier).

• Warning: Legacy context API has been detected. These APIs are no longer supported in React 19+.

  cause This is a warning from React itself, indicating that your application is using the deprecated `getChildContext` or `childContextTypes` APIs, which `react-shortcuts` relies upon.
  fix This warning signals fundamental incompatibility with modern React. The primary 'fix' is to migrate away from `react-shortcuts` to a modern library that does not use the Legacy Context API.

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined.

  cause This error typically indicates that the `Shortcuts` component was not imported correctly or that `react-shortcuts` failed to initialize properly, leading to `Shortcuts` being `undefined` when React tries to render it.
  fix Verify that `import { Shortcuts } from 'react-shortcuts'` is correct and that the `react-shortcuts` package is installed and accessible in your environment. Check for any build or bundling issues that might prevent the component from being resolved.

Warnings

• breaking The library fundamentally relies on React's Legacy Context API (`getChildContext` and `childContextTypes`), which has been deprecated since React 16.3 and is removed entirely in React 19. Attempting to use this library with React 17+ will likely result in warnings or runtime errors related to this API.
  Fix: There is no direct fix for this library to work with modern React without significant re-architecture. Consider migrating to a modern keyboard shortcut library that uses the new Context API or React Hooks, such as `react-hotkeys-hook` or `@keybindy/react`.
• breaking The package's `peerDependencies` (`react` and `react-dom`) are explicitly limited to versions up to `^16`. Using it with React 17 or higher will lead to `npm` or `yarn` peer dependency warnings or installation failures, and likely runtime issues due to the reliance on removed React APIs.
  Fix: Upgrade to a modern keyboard shortcut library compatible with your React version, or pin your project to an older React version (e.g., React 16) which is generally not recommended for new development.
• gotcha The `react-shortcuts` package is abandoned, with the last release over 7 years ago and no recent activity on its GitHub repository. This means there will be no future updates, bug fixes, security patches, or compatibility improvements for newer React versions or browser changes.
  Fix: Avoid using this library for new projects. For existing projects, plan for migration to an actively maintained alternative.
• gotcha The underlying `mousetrap` library often attaches global keyboard listeners. While `react-shortcuts` attempts to scope shortcuts to components, global listeners can still lead to conflicts with other libraries or unintended behaviors if not carefully managed, especially with the `global` prop on the `<Shortcuts>` component.
  Fix: Thoroughly test shortcut interactions across your application, particularly when multiple components might capture the same keys or when integrating with other keyboard-event-driven features. Consider using `stopPropagation` and `preventDefault` as needed within your handlers.

Install

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

Imports

• ShortcutManager
  wrong:

  const ShortcutManager = require('react-shortcuts').ShortcutManager

  correct:

  import { ShortcutManager } from 'react-shortcuts'

  Used to initialize the keymap and manage shortcut instances. Typically instantiated once per application.
• Shortcuts
  wrong:

  const Shortcuts = require('react-shortcuts').Shortcuts

  correct:

  import { Shortcuts } from 'react-shortcuts'

  The React component used to wrap parts of your UI that should respond to specific shortcuts defined in the keymap.

Quickstart

This quickstart demonstrates defining a keymap, creating a ShortcutManager, providing it via `getChildContext` in a parent component, and consuming shortcuts in a child component using the `<Shortcuts>` component. It shows basic shortcut actions and platform-specific keybindings.

import React from 'react';
import PropTypes from 'prop-types';
import { ShortcutManager, Shortcuts } from 'react-shortcuts';

const keymap = {
  TODO_ITEM: {
    MOVE_LEFT: 'left',
    MOVE_RIGHT: 'right',
    MOVE_UP: ['up', 'w'],
    DELETE: {
      osx: ['command+backspace', 'k'],
      windows: 'delete',
      linux: 'delete',
      other: 'delete'
    }
  }
};

const shortcutManager = new ShortcutManager(keymap);

class App extends React.Component {
  getChildContext() {
    return { shortcuts: shortcutManager };
  }

  render() {
    return (
      <div>
        <h1>React Shortcuts Demo</h1>
        <TodoItem />
      </div>
    );
  }
}

App.childContextTypes = {
  shortcuts: PropTypes.object.isRequired
};

class TodoItem extends React.Component {
  _handleShortcuts = (action, event) => {
    switch (action) {
      case 'MOVE_LEFT':
        console.log('Moving left!');
        break;
      case 'MOVE_RIGHT':
        console.log('Moving right!');
        break;
      case 'MOVE_UP':
        console.log('Moving up!');
        break;
      case 'DELETE':
        console.log('Deleting item!');
        break;
      default:
        console.log(`Unhandled action: ${action}`);
    }
    event.preventDefault(); // Prevent default browser behavior
  };

  render() {
    return (
      <Shortcuts name='TODO_ITEM' handler={this._handleShortcuts}>
        <div style={{ padding: '20px', border: '1px solid #ccc', margin: '10px' }}>
          <h3>My Todo Item</h3>
          <p>Try pressing 'left', 'right', 'up', or 'command+backspace' (macOS) / 'delete' (Windows/Linux).</p>
          <p>Focus this area to activate shortcuts.</p>
          <input type="text" placeholder="Type here, shortcuts should be ignored" />
        </div>
      </Shortcuts>
    );
  }
}

export default App;