use-keyup

[![NPM version][npm-image]][npm-url]
[![Actions Status][ci-image]][ci-url]
[![PR Welcome][npm-downloads-image]][npm-downloads-url]

React hook for listening to custom keyup 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.

``bash
npm i @buildinams/use-keyup
`

Usage

To listen to a single key:

`tsx
import useKeyup from "@buildinams/use-keyup";

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

To listen to key modifiers:

`tsx
import useKeyup from "@buildinams/use-keyup";

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

To listen to multiple keys:

`tsx
import useKeyup from "@buildinams/use-keyup";

useKeyup(["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:

`tsx
import useKeyup from "@buildinams/use-keyup";

const elementRef = useRef(null);
useKeyup("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:

`tsx
import useKeyup from "@buildinams/use-keyup";

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

useKeyup("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.

[npm-image]: https://img.shields.io/npm/v/@buildinams/use-keyup.svg?style=flat-square&logo=react
[npm-url]: https://npmjs.org/package/@buildinams/use-keyup
[ci-image]: https://github.com/buildinamsterdam/use-keyup/actions/workflows/test.yml/badge.svg
[ci-url]: https://github.com/buildinamsterdam/use-keyup/actions
[npm-downloads-image]: https://img.shields.io/npm/dm/@buildinams/use-keyup.svg
[npm-downloads-url]: https://npmcharts.com/compare/@buildinams/use-keyup?minimal=true