A lightweight library to manage global keyboard shortcuts for your React application. Just how lightweight is it?
- Your application contains many components that require keyboard shortcuts
- Your application frequently changes keyboard shortcuts depending on the screen
- Your application needs a list of all active shortcuts on the screen
- Your application needs a simple way to manage keyboard shortcuts
We wrote react-keybind with a few main goals:
- No External Dependencies - We wanted full control over the experience and size of the library
- No RFC/Experimental Features - We wanted to build on top of a stable API
- TypeScript Support - We wanted to support TypeScript
- Register shortcuts for single keypresses
- Register shortcuts for combination keypresses (e.g. ctrl+c, ctrl+alt+a)
- Register shortcuts for keypresses held after a duration
- Register shortcuts for sequenced keypresses (e.g. up, up, down, down, enter)
- Creates one listener for all keyboard shortcuts - fast and lightweight!
- Focus - Support executing shortcuts when a particular element is focused
$ npm i react-keybind --saveThis library uses React Context which requires React 16.3+.
This library utilizes TypeScript and exposes a full set of TypeScript definitions.
This library exposes a default withShortcut
Higher-Order Component which is used to
wrap any component that wants to utilize keyboard shortcuts.
Your main application should be wrapped in the exposed <ShortcutProvider />.
import { useCallback, useEffect, useState } from 'react';
import { useShortcut } from 'react-keybind';
// Component that implements a shortcut
const MyComponent = () => {
const {registerShortcut, unregisterShortcut} = useShortcut();
const [state, setState] = useState({
isSaved: false,
});
const save = useCallback(async (e) => {
setState(nextState => ({
...nextState,
isSaved: true,
}));
}, [state]);
useEffect(() => {
registerShortcut(save, ['ctrl+s', 'cmd+s'], 'Save', 'Save the file')
return () => {
unregisterShortcut(['ctrl+s', 'cmd+s'])
}
}, [])
return (
<div>
The file is saved: {state.isSaved ? 'true' : 'false'}
</div>
);
}
// Root application
const App = () => (
<ShortcutProvider>
<MyComponent />
</ShortcutProvider>
);react-keybind exposes a small set of Components to use in your application.
Initializes the main provider for shortcuts. This component should be placed at the root of your application where you want to start listening on keyboard shortcuts.
| Prop | Type | Default | Description |
|---|---|---|---|
| ignoreKeys | string[] | [] | Array of keys to ignore (e.g. ['shift', 'ctrl']) |
| ignoreTagNames | string[] | ['input'] | Array of tagNames to ignore (e.g. ['input', 'article']) |
| preventDefault | boolean | true | Call preventDefault() automatically when a shortcut is executed |
| sequenceTimeout | number | 2000 | How long to wait before checking if a sequence is complete |
Hook to consume shortcuts. Provides the following interface:
{
registerShortcut: (
method: (e?: React.KeyboardEvent<any>) => any,
keys: string[],
title: string,
description: string,
holdDuration?: number,
) => void;
registerSequenceShortcut: (
method: () => any,
keys: string[],
title: string,
description: string,
) => void;
shortcuts: Shortcut[];
triggerShortcut: (key: string) => any;
unregisterShortcut: (keys: string[]) => void;
setEnabled: (enabled: boolean) => void;
}This library was built specifically for dddice, an online platform to roll dice for tabletop roleplaying games.
The dddice platform contains many different screens than handle a wide variety of purposes. Each screen in dddice might contain several dozens of keyboard shortcuts.
Instead of managing each screen individually and keeping track of which shortcuts are used where, we simplify the process by letting components decide which shortcuts they want to define and tracking the list of active shortcuts globally. This is especially useful for rendering a quick "Shortcut Menu" for our users no matter where the user might be in the application.
We open-sourced this library in hopes that other projects might find it useful 💙
MIT