README.md

use-keydown

React hook for listening to custom keydown events.

Introduction

This hook optimizes keyboard event handling by only initializing a single event listener for each target used, resulting in a more streamlined and efficient process.

This library is also SSR safe, and only runs on the client.

Installation

Install this package with npm.

npm i @buildinams/use-keydown

Usage

To listen to a single key:

import useKeydown from "@buildinams/use-keydown";

useKeydown("Escape", () => {}); // Do something on "Escape"...

To listen to key modifiers:

import useKeydown from "@buildinams/use-keydown";

useKeydown("KeyG", (event: KeyboardEvent) => {
  if (event.ctrlKey) // Do something on "Ctrl + G"...
});

To listen to multiple keys:

import useKeydown from "@buildinams/use-keydown";

useKeydown(["KeyA", "KeyG"], () => {}); // Do something on "A" or "G"...

Note: When using multiple keys, the callback will be called if any of the defined keys are pressed.

Using Custom Targets

By default, the hook will listen to the window object. You can however listen to any custom target by passing it as target within the optional config object. This accepts any object that extends EventTarget, such as; document or HTMLElement. For example:

import useKeydown from "@buildinams/use-keydown";

const elementRef = useRef<HTMLDivElement>(null);
useKeydown("Enter", () => {}, { target: elementRef });

Conditionally Listening to Events

You can conditionally listen to events by passing a isEnabled prop the config object. This accepts a boolean value, and will only listen to events if the value is true (default). For example:

import useKeydown from "@buildinams/use-keydown";

const [isEnabled, setIsEnabled] = useState(false);

useKeydown("Enter", () => {}, { isEnabled });

Requirements

This library requires a minimum React version of 17.0.0.

Requests and Contributing

Found an issue? Want a new feature? Get involved! Please contribute using our guideline here.