README
react-keyboard-hooks
React Hooks for keyboard inputs with Typescript
There is a ton of packages that do something very similar, but aren't up to date for today's Typescript & Server-Side Rendering world.
Use these hooks if you want an easy way to add keyboard inputs to your application.
Features
- Written in Typescript
- Works with SSR (ex. Next.js) with no additional configuration
- Simple boolean for single key
- Logic hooks for multiple keys (useAndKeys, useOrKeys)
- Multi-key objects for more complicated uses (useKeys)
- React Hooks API
- Dead simple usage. Just pass in single key or array of keys as strings
- Well tested with Jest & the React Hooks Testing Library
Compatible with React 16.8 and newer.
Does not support Internet Explorer for certain special keys such as Escape. If someone wants to add a map for the old key values feel free to create a PR, but I don't think IE is worth the time anymore.
Installation
To install the package (assuming you have React installed already):
npm install react-keyboard-hooks
# or
yarn install react-keyboard-hooks
Usage
Parameters
Look up key names on the MDN web docs. That is the only parameter you need!
Note: regular unicode keys (ex. the alphabet) are the exact same, even though they aren't listed on the MDN docs.
useKey
const isKeyDown = useKey('Enter')
# or
useKey('Enter', callbackFn)
# or both
const isKeyDown = useKey('Enter', callbackFn)
the useKey hook takes a key value as a string, and returns a boolean if the key is currently pressed/down or not.
Optionally you can use a callback function that runs on the key down instead.
Example:
import React from 'react'
import { useKey } from 'react-keyboard-hooks'
const Example: React.FC = () => {
const isKeyDown = useKey('Enter')
if (isKeyDown) {
console.log('key is down')
}
if (!isKeyDown) {
console.log('key is up')
}
return <div>{isKeyDown ? 'down' : 'up'}</div>
}
Callback Example:
import React, { useState } from 'react'
import { useKey } from 'react-keyboard-hooks'
const Example: React.FC = () => {
const [keyPresses, setKeyPresses] = useState(0)
const callbackFn = () => {
console.log('key is down')
setKeyPresses((previousPresses) => (previousPresses += 1))
}
useKey('Enter', callbackFn)
return <div>{keyPresses}</div>
}
useAnyKeys
const isAnyKeyDown = useAnyKeys(['Enter', 'Tab', 'y'])
# or
useAnyKeys(['Enter', 'Tab', 'y'], callbackFn)
# or both
const isAnyKeyDown = useAnyKeys(['Enter', 'Tab', 'y'], callbackFn)
the useAnyKeys hook takes an array of key values (as strings) and returns true if any of the keys are currently pressed.
Optionally you can use a callback function that runs if any of the keys down instead.
Note: callback doesn't run multiple times if multiple keys are down at the same time.
Example:
import React from 'react'
import { useKeys } from 'react-keyboard-hooks'
const Example: React.FC = () => {
const isAnyKeyDown = useAnyKeys(['Enter', 'Tab', 'y'])
if (isAnyKeyDown) {
console.log('at least one key is down')
}
if (!isAnyKeyDown) {
console.log('all keys are up')
}
return <div>{isAnyKeyDown ? 'down' : 'up'}</div>
}
Callback Example:
import React, { useState } from 'react'
import { useAnyKeys } from 'react-keyboard-hooks'
const Example: React.FC = () => {
const [keyPresses, setKeyPresses] = useState(0)
const callbackFn = () => {
console.log('at least one key is down')
setKeyPresses((previousPresses) => (previousPresses += 1))
}
useAnyKeys(['Enter', 'Tab', 'y'], callbackFn)
return <div>{keyPresses}</div>
}
useAllKeys
const allKeyDown = useAllKeys(['Enter', 'Tab', 'y'])
# or
useAllKeys(['Enter', 'Tab', 'y'], callbackFn)
# or both
const allKeyDown = useAllKeys(['Enter', 'Tab', 'y'], callbackFn)
the useAllKeys hook takes an array of key values (as strings) and returns true if all of the keys are currently pressed.
Optionally you can use a callback function that runs if all of the keys are down instead.
Example:
import React from 'react'
import { useKeys } from 'react-keyboard-hooks'
const Example: React.FC = () => {
const allKeysDown = useAllKeys(['Enter', 'Tab', 'y'])
if (allKeysDown) {
console.log('all keys are down')
}
if (!allKeysDown) {
console.log('at least one key is up')
}
return <div>{allKeysDown ? 'down' : 'up'}</div>
}
Callback Example:
import React, { useState } from 'react'
import { useAllKeys } from 'react-keyboard-hooks'
const Example: React.FC = () => {
const [keyPresses, setKeyPresses] = useState(0)
const callbackFn = () => {
console.log('all keys are down')
setKeyPresses((previousPresses) => (previousPresses += 1))
}
useAllKeys(['Enter', 'Tab', 'y'], callbackFn)
return <div>{keyPresses}</div>
}
useKeys
const keys = useKeys(['Enter', 'Tab', 'y'])
the useKeys hook takes an array of key values (as strings) and returns an object with each key as the key (heh) and the current down/up value as a boolean.
Useful if you want more complicated logic with keypresses, or if you want to use a lot of keys at once (as useKey makes an event listener for each hook)
Example:
import React from 'react'
import { useKeys } from 'react-keyboard-hooks'
const Example: React.FC = () => {
const keys = useKeys(['Enter', 'Tab', 'y'])
if (keys.Enter) {
console.log('Enter key is pressed')
}
if (keys.Tab) {
console.log('Tab key is pressed')
}
return <div>{keys.y ? 'y is down' : 'y is up'}</div>
}