React hook for creating simple keyboard shortcuts.
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.
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");
}
});
useHotkeys(
hotkeys: string | string[],
callback: (event: KeyboardEvent) => void,
eventListenerOptions?: boolean | AddEventListenerOptions
) => void;
Tests use Jest and react-testing-library.
git clone [email protected]:reecelucas/react-use-hotkeys.git
cd react-use-hotkeys
yarn
yarn test