Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/reecelucas/react-use-hotkeys
React hook for creating simple keyboard shortcuts
https://github.com/reecelucas/react-use-hotkeys
hook hotkeys keyboard-shortcuts react-hooks react-hotkeys react-use reactjs
Last synced: about 1 month ago
JSON representation
React hook for creating simple keyboard shortcuts
- Host: GitHub
- URL: https://github.com/reecelucas/react-use-hotkeys
- Owner: reecelucas
- License: mit
- Created: 2019-04-08T15:47:23.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-09T05:40:04.000Z (over 1 year ago)
- Last Synced: 2024-07-18T18:54:28.797Z (about 2 months ago)
- Topics: hook, hotkeys, keyboard-shortcuts, react-hooks, react-hotkeys, react-use, reactjs
- Language: TypeScript
- Homepage:
- Size: 1.04 MB
- Stars: 115
- Watchers: 1
- Forks: 9
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# react-use-hotkeys
React hook for creating simple keyboard shortcuts.
[](https://coveralls.io/github/reecelucas/react-use-hotkeys?branch=master)
[](https://travis-ci.org/reecelucas/react-use-hotkeys)
## Installation
```Bash
npm install @reecelucas/react-use-hotkeys
```
## Example Usage
```ts
import useHotkeys from "@reecelucas/react-use-hotkeys";
```
All hotkey combinations must use valid `KeyBoardEvent` `"key"` values. A full list can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and Wes Bos has created a great [interactive lookup](https://keycode.info/).
```jsx
// 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:
```jsx
// 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!");
});
```
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:
```jsx
useHotkeys("*", (event) => {
console.log("I will run on every keydown event");
if (customKeyLogic(event)) {
console.log("some action");
}
});
```
## Options
### `enabled`
You can disable the hook by passing `enabled: false`. When disabled the hook will stop listening for `keydown` events:
```jsx
useHotkeys(
"Escape",
() => {
console.log("I won't run!");
},
{ enabled: false }
);
```
### `enableOnContentEditable`
By default, the hook will ignore `keydown` events originating from elements with the `contenteditable` attribute, since this behaviour is normally what you want. If you want to override this behaviour you can pass `enableOnContentEditable: true`:
```jsx
useHotkeys(
"Escape",
() => {
console.log("Some action");
},
{ enableOnContentEditable: true }
);
```
### `ignoredElementWhitelist`
By default, the hook will ignore `keydown` events originating from `INPUT` and `TEXTAREA` elements, since this behaviour is normally what you want. If you want to override this behaviour you can use `ignoredElementWhitelist`:
```jsx
useHotkeys(
"Escape",
() => {
console.log("I will now run on input elements");
},
{ ignoredElementWhitelist: ["INPUT"] }
);
useHotkeys(
"Escape",
() => {
console.log("I will now run on input and textarea elements");
},
{ ignoredElementWhitelist: ["INPUT", "TEXTAREA"] }
);
```
### `eventListenerOptions`
You can pass [`AddEventListenerOptions`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#parameters) if you need to listen for `keydown` events in the capturing phase:
```jsx
useHotkeys(
"Escape",
() => {
console.log("I will run in the capturing phase");
},
{
eventListenerOptions: {
capture: true,
},
}
);
```
## Call Signature
```ts
useHotkeys(
hotkeys: string | string[],
callback: (event: KeyboardEvent) => void,
options?: {
enabled?: boolean;
enableOnContentEditable?: boolean;
ignoredElementWhitelist?: ("INPUT" | "TEXTAREA")[];
eventListenerOptions?: AddEventListenerOptions;
}
) => void;
```
## Tests
Tests use [Jest](https://jestjs.io/) and [react-testing-library](https://github.com/kentcdodds/react-testing-library).
```Bash
git clone [email protected]:reecelucas/react-use-hotkeys.git
cd react-use-hotkeys
yarn
yarn test
```
## LICENSE
[MIT](./LICENSE)