Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devlato/react-shortcut
Convenient React component that detects if the given key combination is pressed, and triggers a callback
https://github.com/devlato/react-shortcut
callback hotkey hotkeys javascript konami konamicode react rodney shortcut shortcuts
Last synced: 4 months ago
JSON representation
Convenient React component that detects if the given key combination is pressed, and triggers a callback
- Host: GitHub
- URL: https://github.com/devlato/react-shortcut
- Owner: devlato
- License: mit
- Created: 2017-03-02T00:58:46.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2023-01-05T22:16:48.000Z (about 2 years ago)
- Last Synced: 2024-10-14T05:28:47.182Z (4 months ago)
- Topics: callback, hotkey, hotkeys, javascript, konami, konamicode, react, rodney, shortcut, shortcuts
- Language: TypeScript
- Homepage:
- Size: 6.98 MB
- Stars: 17
- Watchers: 3
- Forks: 7
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# react-shortcut
Convenient React component that detects if the given key combination is pressed, and triggers a callback
[](https://npmjs.org/package/react-shortcut)
[](https://github.com/devlato/react-shortcut/actions?query=workflow%3ARelease)
[](https://github.com/devlato/react-shortcut/actions?query=workflow%3APublish)
[](https://codeclimate.com/github/devlato/react-shortcut/maintainability)
[](https://codeclimate.com/github/devlato/react-shortcut/test_coverage)
[](https://devlato.github.io/react-shortcut/)
[](https://bundlephobia.com/result?p=react-shortcut)
[](https://npmjs.org/package/react-shortcut)
[](https://npmjs.org/package/react-shortcut)
[](https://github.com/devlato/react-shortcut/issues)
## Installation
With npm:
```sh
$ npm install --save react-shortcut
```
Or with Yarn:
```sh
$ yarn add react-shortcut
```
## Using the component
Is very simple and straightforward! There are just a couple of props to pass in.
### Code example
```typescript jsx
import ReactShortcut from 'react-shortcut';
// ...
// Somewhere in your component tree
;
```
### 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:
```typescript jsx
import ReactShortcut from 'react-shortcut';
// Pass in the shortcut keys
// ... or an array of shortcuts
// ... or a string of comma-separated shortcuts
```
#### 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:
```typescript jsx
import ReactShortcut from 'react-shortcut';
// Pass in the shortcut keys
// ... or an array of shortcuts
// ... or a string of comma-separated shortcuts
```
#### Mixed use
Mixing both modes is possible –just follow the same key combination/key sequence convention:
```typescript jsx
import ReactShortcut from 'react-shortcut';
// Array of shortcuts
// ... or a string of comma-separated shortcuts
```
## 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](https://www.npmjs.com/package/react-easter), for adding easter eggs triggered by the keypress.
## License
The library is shipped "as is" under MIT License.
## Contributing [](https://github.com/devlato/react-shortcut/issues)
Feel free to contribute, but don't forget to write tests, mate/matess.