useKeyPress

React hook to detect when a specific key or a combination of keys is pressed or released.

Add the hook via the CLI:

npm

npx @novajslabs/cli add useKeyPress

yarn

npx @novajslabs/cli add useKeyPress

pnpm

pnpm dlx @novajslabs/cli add useKeyPress

Or copy and paste the code into your project:

TypeScript

import { useState, useEffect } from "react";

interface KeyConfig {
  key: string;
  ctrl?: boolean;
  alt?: boolean;
  shift?: boolean;
}

export const useKeyPress = (config: KeyConfig) => {
  const [keyPressed, setKeyPressed] = useState(false);
  const { key: targetKey, ctrl, alt, shift } = config;

  const handleKeyDown = (e: KeyboardEvent) => {
    const { key, ctrlKey, altKey, shiftKey } = e;

    if (
      (!ctrl && !alt && !shift && key === targetKey) ||
      (ctrl && key === targetKey && ctrlKey === ctrl) ||
      (alt && key === targetKey && altKey === alt) ||
      (shift && key === targetKey && shiftKey === shift)
    ) {
      setKeyPressed(true);
    }
  };

  const handleKeyUp = (e: KeyboardEvent) => {
    const { key, ctrlKey, altKey, shiftKey } = e;

    if (
      (!ctrl && !alt && !shift && key === targetKey) ||
      (ctrl && key === targetKey && ctrlKey === ctrl) ||
      (alt && key === targetKey && altKey === alt) ||
      (shift && key === targetKey && shiftKey === shift)
    ) {
      setKeyPressed(false);
    }
  };

  useEffect(() => {
    window.addEventListener("keydown", handleKeyDown);
    window.addEventListener("keyup", handleKeyUp);

    return () => {
      window.removeEventListener("keydown", handleKeyDown);
      window.removeEventListener("keyup", handleKeyUp);
    };
  }, []);

  return keyPressed;
};

JavaScript

import { useState, useEffect } from "react";

export const useKeyPress = (config) => {
  const [keyPressed, setKeyPressed] = useState(false);
  const { key: targetKey, ctrl, alt, shift } = config;

  const handleKeyDown = (e) => {
    const { key, ctrlKey, altKey, shiftKey } = e;

    if (
      (!ctrl && !alt && !shift && key === targetKey) ||
      (ctrl && key === targetKey && ctrlKey === ctrl) ||
      (alt && key === targetKey && altKey === alt) ||
      (shift && key === targetKey && shiftKey === shift)
    ) {
      setKeyPressed(true);
    }
  };

  const handleKeyUp = (e) => {
    const { key, ctrlKey, altKey, shiftKey } = e;

    if (
      (!ctrl && !alt && !shift && key === targetKey) ||
      (ctrl && key === targetKey && ctrlKey === ctrl) ||
      (alt && key === targetKey && altKey === alt) ||
      (shift && key === targetKey && shiftKey === shift)
    ) {
      setKeyPressed(false);
    }
  };

  useEffect(() => {
    window.addEventListener("keydown", handleKeyDown);
    window.addEventListener("keyup", handleKeyUp);

    return () => {
      window.removeEventListener("keydown", handleKeyDown);
      window.removeEventListener("keyup", handleKeyUp);
    };
  }, []);

  return keyPressed;
};

Requirements

React 16.8 or higher

Parameters

config required

Type: object

Specifies the key and optional modifier keys to listen for.

config.key required

Type: string

The name of the key to detect.

config.ctrl

Type: boolean

Represents whether the Ctrl key must be pressed (true) or not (false).

config.alt

Type: boolean

Represents whether the Alt key must be pressed (true) or not (false).

config.shift

Type: boolean

Represents whether the Shift key must be pressed (true) or not (false).

Return values

keyPressed

Type: boolean

It is true when the specified key or combination of keys is currently being pressed and false otherwise.

Example

import { useKeyPress } from "./hooks/useKeyPress";

const App = () => {
  const altS = useKeyPress({ key: "s", alt: true });

  return <div>{altS ? "Saving document..." : "Type your text here..."}</div>;
};

export default App;

Use cases

Here are some use cases where this React hook is useful:

• Use arrow keys or combinations like Ctrl + Arrow keys for navigating through a list or a grid
• Implement shortcuts for users who rely on keyboard navigation, such as opening a menu with Alt + m
• In a web-based game, use WASD or arrow keys for movement, and Space for jumping or shooting