Package Exports

@imedadel/react-use-hotkeys

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@imedadel/react-use-hotkeys) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

react-use-hotkeys

React hook for creating simple keyboard shortcuts.

npm bundle size (scoped) npm (scoped) GitHub

Installation

npm install @reecelucas/react-use-hotkeys

This package has a single dependency, a tiny shim called shim-keyboard-event-key that normalises the non-standard KeyBoardEvent.key values implemented in Edge and IE.

Example Usage

All hotkey combinations must use valid KeyBoardEvent "key" values. A full list can be found on MDN and Wes Bos has created a great interactive lookup.

// Single keys
useHotkeys('Escape', () => {
  console.log('Some action');
});

useHotkeys('F7', () => {
  console.log('Some action');
});

// Modifier combinations
useHotkeys('Meta+Shift+z', () => {
  console.log('Some action');
});

// Key sequences
useHotkeys('w s d', () => {
  console.log('Some action');
});

useHotkeys('w " " d', () => {
  // space key in sequence (`w ' ' d` also works)
  console.log('Some action');
});

// Multiple key combinations mapped to the same callback
useHotkeys(['Control+z', 'Meta+z'], () => {
  console.log('Some action');
});

useHotkeys(['a', 'Meta+z', 'w s d'], () => {
  console.log('Some action');
})

The following patterns are not supported:

// Modifier keys in sequences
useHotkeys('Control i d', () => {
  console.log("I won't run!");
});

// Modifier combinations in sequences
useHotkeys('Control+z i d', () => {
  console.log("I won't run!");
});

You can pass AddEventListenerOptions if you need to listen for keydown events in the capturing phase:

useHotkeys('Escape', () => {
  console.log('Some action');
}, true);

useHotkeys('Escape', () => {
  console.log('Some action');
}, { capture: true });

If you find a use case where the API is too restrictive you can use the escape hatch to perform whatever custom logic you need:

useHotkeys('*', event => {
  console.log("I will run on every keydown");

  if (customKeyLogic(event)) {
    console.log("some action");
  }
});

Call Signature

useHotkeys(
  hotkeys: string | string[],
  callback: (event: KeyboardEvent) => void,
  eventListenerOptions?: boolean | AddEventListenerOptions
) => void;

Tests

Tests use Jest and react-testing-library.

git clone git@github.com:reecelucas/react-use-hotkeys.git
cd react-use-hotkeys
yarn
yarn test

LICENSE

MIT