React hook for listening to custom keyup events.
npm install @buildinams/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.
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.
Install this package with npm.
``bash`
npm i @buildinams/use-keyup
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.
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
useKeyup("Enter", () => {}, { target: elementRef });
`
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 });
`
This library requires a minimum React version of 17.0.0`.
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