README.md

react-shortcut

Convenient React component that detects if the given key combination is pressed, and triggers a callback

Installation

With npm:

$ npm install --save react-shortcut

Or with Yarn:

$ yarn add react-shortcut

Using the component

Is very simple and straightforward! There are just a couple of props to pass in.

Code example

import ReactShortcut from 'react-shortcut';

// ...
// Somewhere in your component tree
<ReactShortcut
  keys={/* String or array of strings containing the keys to be pressed, in any supported format */}
  onKeysPressed={/* Callback when target key combination is pressed */}
/>;

Props

All the props are required.

Name	Description	Type
keys	A string containing comma-separated key combinations or/and key sequences, or an array of such strings	A string or an array of strings
onKeysPressed	A callback to be triggered when the user presses any of the specified key combinations	A function with no arguments

Key combinations and Key sequences

The component supports both key combinations and key sequences.

Key combinations

A key combination is a string of key names separated by a plus sign, that describes what keys the user has to press at the same time, to execute the callback specified using onKeysPressed prop.

Examples: Command+Shift+Left, Ctrl+P.

To react on the keys combination(s) press, use the following format:

import ReactShortcut from 'react-shortcut';

// Pass in the shortcut keys
<ReactShortcut
    keys="command+k"
    onKeysPressed={doSomethingOnShortcutPress}
/>

// ... or an array of shortcuts
<ReactShortcut
    keys={['command+k', 'command+m']}
    onKeysPressed={doSomethingOnShortcutPress}
/>

// ... or a string of comma-separated shortcuts
<ReactShortcut
    keys="command+k,command+m"
    onKeysPressed={doSomethingOnShortcutPress}
/>

Key sequences

A key sequence is a string of key names separated by a space character, that lists out the keys the user has to press one by one, to trigger the callback specified using onKeysPressed prop.

Examples: Up Up Down Down Left Right Left Right B A Enter, k o n a m i.

To react on the keys sequence(s) press, use the following format:

import ReactShortcut from 'react-shortcut';

// Pass in the shortcut keys
<ReactShortcut
    keys="k o n a m i"
    onKeysPressed={doSomethingOnShortcutPress}
/>

// ... or an array of shortcuts
<ReactShortcut
    keys={['k o n a m i', 'm a r i o b r o s enter']}
    onKeysPressed={doSomethingOnShortcutPress}
/>

// ... or a string of comma-separated shortcuts
<ReactShortcut
    keys="k o n a m i,m a r i o b r o s enter"
    onKeysPressed={doSomethingOnShortcutPress}
/>

Mixed use

Mixing both modes is possible –just follow the same key combination/key sequence convention:

import ReactShortcut from 'react-shortcut';

// Array of shortcuts
<ReactShortcut
    keys={['k o n a m i', 'shift+command+m']}
    onKeysPressed={doSomethingOnShortcutPress}
/>

// ... or a string of comma-separated shortcuts
<ReactShortcut
    keys="k o n a m i,shift+command+m"
    onKeysPressed={doSomethingOnShortcutPress}
/>

FAQ

Does it support TypeScript?

It does. Moreover, it's implemented in TypeScript.

Do I have to use component only in the root level component?

Nope. The component adds a global keyboard event listener and doesn't prevent events from bubbling or capturing.

What if my app needs to support multiple shortcuts?

Just use the component as many times as you need, just make sure the shortcuts aren't repeated.

Do I have to specify the shortcuts in lower case only?

No, the case doesn't matter.

Any open-source examples of using this library?

There's an official™️ one called react-easter, for adding easter eggs triggered by the keypress.

License

The library is shipped "as is" under MIT License.

Contributing

Feel free to contribute, but don't forget to write tests, mate/matess.