README.md

react-use-hotkeys

React hook for creating simple keyboard shortcuts.

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 [email protected]:reecelucas/react-use-hotkeys.git
cd react-use-hotkeys
yarn
yarn test

LICENSE

MIT