react-keybinds

A lightweight library to manage keyboard shortcuts for your React application

Install

Using npm

npm i react-keybinds

Using Yarn

yarn add react-keybinds

Using pnpm

pnpm add react-keybinds

Usage

_{You can take a look at the example}

1. Configuring the KeyBind provider

import{KeyBindProvider}from'react-keybinds';constApp=()=>{return(<KeyBindProvider>
hello world
</KeyBindProvider>);};

_{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}

constApp=()=>{return(<KeyBindProviderdebounce={500}>
hello world
</KeyBindProvider>);}

2. Global shortcuts

You can register commands globally

import{KeyBindProvider,ShortcutType}from'react-keybinds';constGLOBAL_COMMANDS: ShortcutType[]=[{keys: {Mac: ['Control','Shift','P'],Windows: ['Control','Shift','P'],},label: 'Test command',callback: ()=>{alert('Hello world');},},];constApp=()=>{return(<KeyBindProvidershortcuts={GLOBAL_COMMANDS}>
hello world
</KeyBindProvider>);};

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.

import{KeyBindProvider,useKeyBind}from'react-keybinds';constRegisterShortcutButton=()=>{const{registerShortcut}=useKeyBind();consthandleClickRegister=()=>{registerShortcut({keys: {Mac: ['Shift','*','_'],},label: 'This is a keyboard shortcut',callback: ()=>{alert('Hello world');},});};return(<div><buttononClick={handleClickRegister}>Register shortcut</button></div>);};constApp=()=>{return(<KeyBindProvider><RegisterShortcutButton/></KeyBindProvider>);};

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}

import*asReactfrom'react';import{useMemo,useState}from'react';import{ShortcutType,useKeyBind,useRegisterShortcut}from'react-keybinds';importinspirefrom'../data/inspire';constRegisterOnMount=()=>{const[text,setText]=useState(inspire[0]);const{getKeysByPlatform}=useKeyBind();constshortcut: ShortcutType=useMemo(()=>({keys: {Windows: ['Control','Enter'],},label: 'Inspired command',callback: ()=>{constrandomIndex=Math.floor(Math.random()*inspire.length);setText(inspire[randomIndex]);},}),[]);useRegisterShortcut(shortcut);// register on mountconstkeysForInspire=getKeysByPlatform(shortcut);return(<div><h1>Inspire command</h1><p>
Press: <strong>{keysForInspire?.keys?.join(' + ')}</strong>{' '}</p><blockquote>{`"${text}"`}</blockquote></div>);};exportdefaultRegisterOnMount;

4. List registered shortcuts

You can list the registered shortcuts using the useKeyBind hook

import{KeyBindProvider,useKeyBind}from'react-keybinds';constShowShortcuts=()=>{const{shortcuts}=useKeyBind();constshortcutsList=shortcuts?.map((shortcut,index)=>{return(<divkey={index}><span>{shortcut.label}</span><ul>{Object.entries(shortcut.keys).map(([key,values],i)=>(<likey={`${key}-${i}`}>{key}: <strong>{values.join(' + ')}</strong></li>))}</ul></div>);});return(<div><h1>Registered Shortcuts</h1>{shortcutsList}</div>);};constApp=()=>{return(<KeyBindProvider><ShowShortcuts/></KeyBindProvider>);};

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.

constshortcut: ShortcutType=useMemo(()=>({keys: {Windows: ['Control','Enter'],},label: 'Inspired command',callback: ()=>{},}),[]);constinformationForInspire=getKeysByPlatform(shortcut);// {platform: 'Windows', keys: ['Control', 'Enter']}

• If you want to have more information about the current platform, you can use the usePlatform hook

import{usePlatform}from'react-keybinds';constApp=()=>{constplatform=usePlatform();return(<div><h1>Current platform: {platform.currentPlatform()}</h1><h1>Is Windows: {platform.isWindows()}</h1></div>);};

• If you want to take a look at a list of all the keys for different platforms, you can use the following link