https://github.com/lifespikes/react-keybinds
A lightweight library to manage keyboard shortcuts for your React application
https://github.com/lifespikes/react-keybinds
keybinds keyboard lifespikes react shortcuts shortcuts-app
Last synced: about 1 year ago
JSON representation
A lightweight library to manage keyboard shortcuts for your React application
- Host: GitHub
- URL: https://github.com/lifespikes/react-keybinds
- Owner: lifespikes
- License: mit
- Created: 2022-11-15T02:26:24.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-18T07:00:54.000Z (about 2 years ago)
- Last Synced: 2025-03-27T06:34:37.431Z (over 1 year ago)
- Topics: keybinds, keyboard, lifespikes, react, shortcuts, shortcuts-app
- Language: TypeScript
- Homepage:
- Size: 2.5 MB
- Stars: 14
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-keybinds
[
](https://www.npmjs.com/package/react-keybinds)
[
](https://bundlephobia.com/package/react-keybinds)
A lightweight library to manage keyboard shortcuts for your React application
# Install
#### Using npm
```bash
npm i react-keybinds
```
#### Using Yarn
```bash
yarn add react-keybinds
```
#### Using pnpm
```bash
pnpm add react-keybinds
```
# Usage
You can take a look at the [example](./example)
### 1. Configuring the KeyBind provider
```tsx
import {KeyBindProvider} from 'react-keybinds';
const App = () => {
return (
hello world
);
};
```
It is recommended that you place the provider at the beginning of the component tree.
By default, the provider will have a debounce on key presses events of 1000ms, you can change this value by passing the `debounce` prop to the provider
```tsx
const App = () => {
return (
hello world
);
}
```
### 2. Global shortcuts
You can register commands globally
```tsx
import {KeyBindProvider, ShortcutType} from 'react-keybinds';
const GLOBAL_COMMANDS: ShortcutType[] = [
{
keys: {
Mac: ['Control', 'Shift', 'P'],
Windows: ['Control', 'Shift', 'P'],
},
label: 'Test command',
callback: () => {
alert('Hello world');
},
},
];
const App = () => {
return (
hello world
);
};
```
### 3. Register shortcuts
You can register a command in a specific part of your application. This is useful when we want to execute logic from a
handler that exists in a specific component.
```tsx
import {KeyBindProvider, useKeyBind} from 'react-keybinds';
const RegisterShortcutButton = () => {
const {registerShortcut} = useKeyBind();
const handleClickRegister = () => {
registerShortcut({
keys: {
Mac: ['Shift', '*', '_'],
},
label: 'This is a keyboard shortcut',
callback: () => {
alert('Hello world');
},
});
};
return (
Register shortcut
);
};
const App = () => {
return (
);
};
```
You can also register a shortcut when a component is mounted. Like this:
When you use the `useRegisterShortcut` hook it is necessary to use the `useMemo` hook
```tsx
import * as React from 'react';
import {useMemo, useState} from 'react';
import {ShortcutType, useKeyBind, useRegisterShortcut} from 'react-keybinds';
import inspire from '../data/inspire';
const RegisterOnMount = () => {
const [text, setText] = useState(inspire[0]);
const {getKeysByPlatform} = useKeyBind();
const shortcut: ShortcutType = useMemo(
() => ({
keys: {
Windows: ['Control', 'Enter'],
},
label: 'Inspired command',
callback: () => {
const randomIndex = Math.floor(Math.random() * inspire.length);
setText(inspire[randomIndex]);
},
}),
[]
);
useRegisterShortcut(shortcut); // register on mount
const keysForInspire = getKeysByPlatform(shortcut);
return (
Inspire command
Press: {keysForInspire?.keys?.join(' + ')}{' '}
{`"${text}"`}
);
};
export default RegisterOnMount;
```
### 4. List registered shortcuts
You can list the registered shortcuts using the useKeyBind hook
```tsx
import {KeyBindProvider, useKeyBind} from 'react-keybinds';
const ShowShortcuts = () => {
const {shortcuts} = useKeyBind();
const shortcutsList = shortcuts?.map((shortcut, index) => {
return (
{shortcut.label}
{Object.entries(shortcut.keys).map(([key, values], i) => (
-
{key}: {values.join(' + ')}
))}
);
});
return (
Registered Shortcuts
{shortcutsList}
);
};
const App = () => {
return (
);
};
```
## Notes
- If a user is using a platform for which you did not specify the keys, it will default to the keys of a platform that
you have configured.
If you want to see which platform the keys will be taken from, you can use the `getKeysByPlatform` method.
```tsx
const shortcut: ShortcutType = useMemo(
() => ({
keys: {
Windows: ['Control', 'Enter'],
},
label: 'Inspired command',
callback: () => {
},
}),
[]
);
const informationForInspire = getKeysByPlatform(shortcut); // {platform: 'Windows', keys: ['Control', 'Enter']}
```
- If you want to have more information about the current platform, you can use the usePlatform hook
```tsx
import { usePlatform } from 'react-keybinds';
const App = () => {
const platform = usePlatform();
return (
Current platform: {platform.currentPlatform()}
Is Windows: {platform.isWindows()}
);
};
```
- If you want to take a look at a list of all the keys for different platforms, you can use the following [link](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)