@react-hook/hotkey
v3.1.0TypeScript
A React hook for invoking a callback when hotkeys are pressed
0/weekUpdated 3 years agoMITUnpacked: 62.6 KB
Published by Jared Lunde
npm install @react-hook/hotkey
useHotkey()
npm i @react-hook/hotkey
A React hook for invoking a callback when hotkeys are pressed. This hook also
provides interop between event.key and event.which - you provide a string, and
the library turns it into an event.which key code if it has to.
For better TypeScript support, this library doesn't have a special syntax à la
the is-hotkey package. It uses plain JS objects and your build will fail
if you've included a typo.
Quick Start
``jsx harmony
import * as React from 'react'
import {useHotkey, useHotkeys} from '@react-hook/hotkey'
const OneHotkey = () => {
const ref = React.useRef(null)
const save = () => {}
// creates a hotkey for Command|Control + S keys
useHotkey(ref, ['mod', 's'], save)
return
}
const OneHotkeySingleCharacter = () => {
const ref = React.useRef(null)
const exit = () => {}
// creates a hotkey for the escape key
useHotkey(ref, 'esc', exit)
return
}
const MultipleHotkeys = () => {
const ref = React.useRef(null)
useHotkeys(
// Hotkey map
[
[['mod', 's'], save],
[['mod', 'p'], print],
['esc', blur],
['enter', submit],
]
)
return
}
`
API
$3
This is a hook for creating a single hotkey.
#### Arguments
| Argument | Type | Required? | Description |
| -------- | ---------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| target | React.RefObject<T> | T | Window | Document | null | Yes | The React ref, window, or document to add the hotkey to |keydown
| hotkey | [Hotkey | Hotkey[]](#hotkey) | Yes | When the key and all of the modifiers in a event match those defined here, the callback below will be invoked. See SpecialCodes, Aliases, and Modifiers for possible keys in addition the standard keys. |HotkeyCallback
| callback | | Yes | A callback that takes action on the hotkey event. |
#### Returns React.MutableRefObject
$3
This is a hook for creating multiple hotkeys that respond to a singular keyboard event.
#### Arguments
| Argument | Type | Required? | Description |
| ------------- | ---------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------- |
| target | React.RefObject<T> | T | Window | Document | null | Yes | The React ref, window, or document to add the hotkey to |HotkeyCallback
| hotkeyMapping | [[Hotkey | Hotkey[]](#hotkey), ][] | Yes | These are the same arguments defined in useHotkey, but in a mapped array form. |
#### Returns React.MutableRefObject
Types
$3
`typescript`
type HotkeyCallback = (event: KeyboardEvent) => void
$3
`typescript`
type Hotkey =
| keyof SpecialCodes
| keyof Modifiers
| keyof Aliases
| 1
| 2
| 3
| 4
| 5
| 6
| 7
| 8
| 9
| 0
| '1'
| '2'
| '3'
| '4'
| '5'
| '6'
| '7'
| '8'
| '9'
| '0'
| 'a'
| 'b'
| 'c'
| 'd'
| 'e'
| 'f'
| 'g'
| 'h'
| 'i'
| 'j'
| 'k'
| 'l'
| 'm'
| 'n'
| 'o'
| 'p'
| 'q'
| 'r'
| 's'
| 't'
| 'u'
| 'v'
| 'w'
| 'x'
| 'y'
| 'z'
$3
`typescript': 192
interface SpecialCodes {
backspace: 8
tab: 9
enter: 13
shift: 16
control: 17
alt: 18
pause: 19
capslock: 20
escape: 27
' ': 32
pageup: 33
pagedown: 34
end: 35
home: 36
arrowleft: 37
arrowup: 38
arrowright: 39
arrowdown: 40
insert: 45
delete: 46
meta: 91
numlock: 144
scrolllock: 145
';': 186
'=': 187
',': 188
'-': 189
'.': 190
'/': 191
'
'[': 219
'\\': 220
']': 221
"'": 222
f1: 112
f2: 113
f3: 114
f4: 115
f5: 116
f6: 117
f7: 118
f8: 119
f9: 120
f10: 121
f11: 122
f12: 123
f13: 124
f14: 125
f15: 126
f16: 127
f17: 128
f18: 129
f19: 130
f20: 131
}
``
$3
`typescriptcommand
interface Aliases {
break: 'pause'
cmd: 'meta'
command: 'meta'
ctrl: 'control'
del: 'delete'
down: 'arrowdown'
esc: 'escape'
left: 'arrowleft'
// will respond to the key on a mac andcontrol
// to the key everywhere else`
mod: 'meta' | 'control'
option: 'alt'
return: 'enter'
right: 'arrowright'
space: ' '
spacebar: ' '
up: 'arrowup'
windows: 'meta'
}
$3
`typescript``
interface Modifiers {
alt: 'altKey'
control: 'ctrlKey'
meta: 'metaKey'
shift: 'shiftKey'
}
Credits
Full credit for the key code interop portion goes to Ian Storm Taylor
and his library is-hotkey.
LICENSE
MIT