Keyboard Shortcuts with React Hooks

Useful Hooks

In order to properly implement this functionality, we'll be using a combination of three hooks:

• useEffect allows us to add side effects to our application. In our specific case, we will use this hook to create an event listeners when our component mounts. It will also remove listeners when the component unmounts.
• useReducer allows us to keep a state of pressed keys. We will use a keydown event to keep track of held down keys and a keyup event to keep track of released keys.
• useCallback is simply a performance optimization hook which we use to wrap our event listener callback function. If we do not do this, React will re-instantiate a new function every time our custom hook re-renders, which will happen quite often.‍

Understand the KeyboardEvent

To listen for keypresses in our application, we will be registering and event listen for the keydown/keyup events. This will call our listener function with a KeyboardEvent which has a number of properties that will allow us to build our custom hook. While there are many properties, we will only be focused on two specific properties.

• KeyboardEvent.repeat is a read only property that returns a Boolean that is set to true if the key is being held down such that it is automatically repeating.
• KeyboardEvent.key is a read only property that returns a String that is set to the current key that was pressed. This also takes into account any modifier keys that might have affected the KeyboardEvent. For example, holding down the Shift then pressing the number 4, will set the KeyboardEvent.key property to "$" on the US Keyboard.‍

Creating the hooks

To start we will create a new function and called it as follows:

-- CODE language-jsx keep-markup --
const useKeyboardShortcut = (shortcutKeys, callback) => {}

Our custom hook will accept two parameters, the first is an array of strings which should match the the KeyboardEvent's key property. The second is a callback function that should be called when the keyboard shortcut is invoked.

Just to ensure that there is no user error, we will add some warnings to our custom hook to make sure that all of the parameter conditions are met:

-- CODE language-jsx keep-markup --
if (!Array.isArray(shortcutKeys))    
  thrownew Error(      
    "The first parameter to `useKeyboardShortcut` must be an ordered array of `KeyboardEvent.key` strings."    
  );

if (!shortcutKeys.length)  
  thrownew Error(    
    "The first parameter to `useKeyboardShortcut` must contain at least one `KeyboardEvent.key` string."  
  );

‍if (!callback || typeof callback !== "function")  
  thrownew Error(    
    "The second parameter to `useKeyboardShortcut` must be a function that will be invoked when the keys are pressed."  
);

Next we will create a state object and a reducer in order to track key presses and releases. Using our shortcutKey's array, we will construct a state object that tracks whether a key is being held down.

-- CODE language-jsx keep-markup --
const initalKeyMapping = shortcutKeys.reduce((currentKeys, key) => {  
  currentKeys[key] = false;  
  return currentKeys;
}, {});

‍const [keys, setKeys] = useReducer(keysReducer, initalKeyMapping);

This will convert an array of keys to an object that is shaped as such:

-- CODE language-jsx keep-markup --
{  
  shift: false,  
  e: false
}

Next we will add two event listeners, one for keydown events and the other for keyup events. Using the useEffect hook, we will add these event listeners on the hooks mount.

-- CODE language-jsx keep-markup --
useEffect(() => {  
  window.addEventListener("keydown", keydownListener, true);  
  return () => window.removeEventListener("keydown", keydownListener, true);
}, [keydownListener]);

useEffect(() => {  
  window.addEventListener("keyup", keyupListener, true);  
  return () => window.removeEventListener("keyup", keyupListener, true);
}, [keyupListener]);

This will add an event listener to the window and remove it when the component using the hook unmounts. As you can see, each event listener is passed a specific handler function.‍

Keydown Handling

For the keydown event, the handler functions is quite simple:

-- CODE language-jsx keep-markup --
const keydownListener = useCallback(  
  keydownEvent => {    
    const { key, target, repeat } = keydownEvent;    
    if (repeat) return;    
    if (blacklistedTargets.includes(target.tagName)) return;    
    if (!shortcutKeys.includes(key)) return;    

    if (!keys[key])      
      setKeys({ type: "set-key-down", key });  
  },  
  [shortcutKeys, keys]
);

In order to prevent this function being recreated on every update of this hook, we will wrap the function in useCallback which will only recreate the function if the shortcutKeys or the keys objects have changed.

We check to make sure that this KeyboardEvent is not a repeating event, which means that this is the first key down event of this key. If it's repeating, that means that the key is being held down and has already been processed.

Next we get the key that was pressed and the DOM element that generated this keydown event. We check to make sure that DOM element isn't an input or textarea because we don't want to trigger keyboard shortcuts when the user is typing.

Next we check to make sure that the pressed key is in the shortcutKeys array, this way we are only processing keys are that needed for this keyboard shortcut.

Finally after all of those checks have passed, we fire a set-key-down action with the key which will update the state to indicate the key is being held down.‍

Keyup Handling

Much like the keyup listener, the keyup makes all of the same checks the only difference is that it will fire the set-key-up action, which will update the state to indicate the key has been released:

-- CODE language-jsx keep-markup --
const keyupListener = useCallback(  
  keyupEvent => {    
    const { key, target } = keyupEvent;    
    if (blacklistedTargets.includes(target.tagName)) return;    
    if (!shortcutKeys.includes(key)) return;    
‍
    if (keys[key])      
      setKeys({ type: "set-key-up", key });  
  },  
  [shortcutKeys, keys]
);‍

Triggering the keyboard callback function

Finally we will create one more useEffect hook that will fire our callback function for the keyboard shortcut. It will check out keys state object to make sure that all of the keys are currently being held down. Once that criteria is met it will fire the callback function.

-- CODE language-jsx keep-markup --
useEffect(() => {  
  if (!Object.values(keys).filter(value => !value).length) callback(keys)
}, [callback, keys])

After everything is complete, the entire keyboard shortcut hook should be about 80 lines of code.

In order to use our keyboard shortcut hook, we simply import the useKeyboardShortcut function and call it in our component.

-- CODE language-jsx keep-markup --
import React, { useState, useCallback } from 'react';
‍import useKeyboardShortcut from 'use-keyboard-shortcut';

‍functionApp() {  
  const [showImage, setShowImage] = useState(false)  
  const keys = ['Shift', 'E']  
  const handleKeyboardShortcut = useCallback(keys => {    
    setShowImage(currentShowImage => !currentShowImage)  
  }, [setShowImage])  

  useKeyboardShortcut(keys, handleKeyboardShortcut)  
  
  return (    
    <div style={styles.main}>      
      {showImage && (<img style={styles.image} alt="FullStackLabs Logo" src="/icon.png" />)}      
      <h1 style={styles.text}>{`Press ${keys.join(' + ')} to show image.`}</h1>
    </div>  );}

const styles = {...}

export default App;

In this example, we create a keyboard shortcut that listens for the Shift and E keys, when both of those are pressed, we should see an image appear on the screen.

All of the code in this post can be found here, this package can also be installed from npm.

---

At FullStack Labs, we pride ourselves on our ability to push the capabilities of cutting-edge frameworks like React. Interested in learning more about speeding up development time on your next project? Contact us.