React hook for registering keybinds
npm install use-keyuseKey is a react hook for registering keybinds.
``
$ yarn add use-key
Function signature:
`ts
interface Keybinds {
[keybind: string]: Callback
}
useKey(keybinds: Keybinds)
`
Examples:
`js
// Single keys
useKey({
'Escape': () => console.log('action')
})
// Modifier combinations
useKey({
'Meta+Shift+z': () => console.log('action')
})
// Key sequences (callback fires when you press "w", then "s", then "d")
useKey({
'w s d': () => console.log('action')
})
// Space key in sequence (w ' ' d also works)
useKey(
'w " " d': () => console.log('action')
})
// Multiple key combinations mapped to the same callback
useKey({
'Control+z, Meta+z': () => console.log('action')
})
useKey({
'a, Meta+z, w s d': () => console.log('action')
})
// Multiple keybinds registered at once
useKey({
'a': () => console.log('action'),
'b': () => console.log('action 2')
})
`
useKey throws an error if you register the same keybind twice.
`js
useKey('a', () => console.log('action'))
useKey('a', () => console.log('action 2'))
// => Error: Keybind "a" already in use.
`
This also applies to keybinds using modifier combinations and sequences.
For every useKey, there is an associated useEffect. Across every useKey, there is only one shared event listener that handles every keybind.
Why? This means you can register a lot of keybinds without adding many global listeners. This should (theoretically) improve performance with a large number of registered keybinds. I also just wanted to see if and how it would work.
Notes to self, things to add.
Allow keybinds to be scoped to a DOM element instead of being global. Listeners should be deduped, just like global ones.
Support both string and React.Ref for selector?
`js`
useKey({
'a': {
ref: 'div.container',
callback: () => console.log('action')
}
})
Allow the delay for key sequences to be configurable. If after maxDelay milliseconds the next key in the sequence hasn't been pressed, reset the list of already pressed keys.
`js`
useKey({
'a b c': {
callback: () => console.log('action'),
maxDelay: 500
}
})
Useful class, may as well expose it.
`js
import { KeyHandler } from 'use-key'
const handler = new KeyHandler('a', () => console.log('action'))
window.addEventListener('keydown', handler.handle)
`
- Triggering a callback doesn't clear the all of the sequence timers
useKey is inspired by and based on the logic in react-use-hotkeys`.
Thanks to Giuseppe for ideas on how to share event listeners across multiple calls to a hook.