---

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

1import * as React from 'react'
2import {useHotkey, useHotkeys} from '@react-hook/hotkey'
3
4const OneHotkey = () => {
5  const ref = React.useRef(null)
6  const save = () => {}
7  // creates a hotkey for Command|Control + S keys
8  useHotkey(ref, ['mod', 's'], save)
9  return <textarea ref={ref} />
10}
11
12const OneHotkeySingleCharacter = () => {
13  const ref = React.useRef(null)
14  const exit = () => {}
15  // creates a hotkey for the escape key
16  useHotkey(ref, 'esc', exit)
17  return <textarea ref={ref} />
18}
19
20const MultipleHotkeys = () => {
21  const ref = React.useRef(null)
22
23  useHotkeys(
24    // Hotkey map
25    [
26      [['mod', 's'], save],
27      [['mod', 'p'], print],
28      ['esc', blur],
29      ['enter', submit],
30    ]
31  )
32
33  return <textarea ref={ref} />
34}

API

useHotkey(hotkey, callback)

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
hotkey	Hotkey | Hotkey[]	Yes	When the key and all of the modifiers in a keydown event match those defined here, the callback below will be invoked. See SpecialCodes, Aliases, and Modifiers for possible keys in addition the standard keys.
callback	HotkeyCallback	Yes	A callback that takes action on the hotkey event.

Returns React.MutableRefObject<T>

useHotkeys(hotkeyMapping)

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
hotkeyMapping	[Hotkey | Hotkey[], HotkeyCallback][]	Yes	These are the same arguments defined in useHotkey, but in a mapped array form.

Returns React.MutableRefObject<T>

Types

HotkeyCallback

1type HotkeyCallback = (event: KeyboardEvent) => void

Hotkey

1type Hotkey =
2  | keyof SpecialCodes
3  | keyof Modifiers
4  | keyof Aliases
5  | 1
6  | 2
7  | 3
8  | 4
9  | 5
10  | 6
11  | 7
12  | 8
13  | 9
14  | 0
15  | '1'
16  | '2'
17  | '3'
18  | '4'
19  | '5'
20  | '6'
21  | '7'
22  | '8'
23  | '9'
24  | '0'
25  | 'a'
26  | 'b'
27  | 'c'
28  | 'd'
29  | 'e'
30  | 'f'
31  | 'g'
32  | 'h'
33  | 'i'
34  | 'j'
35  | 'k'
36  | 'l'
37  | 'm'
38  | 'n'
39  | 'o'
40  | 'p'
41  | 'q'
42  | 'r'
43  | 's'
44  | 't'
45  | 'u'
46  | 'v'
47  | 'w'
48  | 'x'
49  | 'y'
50  | 'z'

SpecialCodes

1interface SpecialCodes {
2  backspace: 8
3  tab: 9
4  enter: 13
5  shift: 16
6  control: 17
7  alt: 18
8  pause: 19
9  capslock: 20
10  escape: 27
11  ' ': 32
12  pageup: 33
13  pagedown: 34
14  end: 35
15  home: 36
16  arrowleft: 37
17  arrowup: 38
18  arrowright: 39
19  arrowdown: 40
20  insert: 45
21  delete: 46
22  meta: 91
23  numlock: 144
24  scrolllock: 145
25  ';': 186
26  '=': 187
27  ',': 188
28  '-': 189
29  '.': 190
30  '/': 191
31  '`': 192
32  '[': 219
33  '\\': 220
34  ']': 221
35  "'": 222
36  f1: 112
37  f2: 113
38  f3: 114
39  f4: 115
40  f5: 116
41  f6: 117
42  f7: 118
43  f8: 119
44  f9: 120
45  f10: 121
46  f11: 122
47  f12: 123
48  f13: 124
49  f14: 125
50  f15: 126
51  f16: 127
52  f17: 128
53  f18: 129
54  f19: 130
55  f20: 131
56}

Aliases

1interface Aliases {
2  break: 'pause'
3  cmd: 'meta'
4  command: 'meta'
5  ctrl: 'control'
6  del: 'delete'
7  down: 'arrowdown'
8  esc: 'escape'
9  left: 'arrowleft'
10  // will respond to the `command` key on a mac and
11  // to the `control` key everywhere else
12  mod: 'meta' | 'control'
13  option: 'alt'
14  return: 'enter'
15  right: 'arrowright'
16  space: ' '
17  spacebar: ' '
18  up: 'arrowup'
19  windows: 'meta'
20}

Modifiers

1interface Modifiers {
2  alt: 'altKey'
3  control: 'ctrlKey'
4  meta: 'metaKey'
5  shift: 'shiftKey'
6}

Credits

Full credit for the key code interop portion goes to Ian Storm Taylor and his library is-hotkey.

LICENSE

MIT