react-use-hotkeys
React hook for creating simple keyboard shortcuts.
Installation
npm install @reecelucas/react-use-hotkeysThis 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