@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

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 <textarea ref={ref} />
}

const OneHotkeySingleCharacter = () => {
  const ref = React.useRef(null)
  const exit = () => {}
  // creates a hotkey for the escape key
  useHotkey(ref, 'esc', exit)
  return <textarea ref={ref} />
}

const MultipleHotkeys = () => {
  const ref = React.useRef(null)

  useHotkeys(
    // Hotkey map
    [
      [['mod', 's'], save],
      [['mod', 'p'], print],
      ['esc', blur],
      ['enter', submit],
    ]
  )

  return <textarea ref={ref} />
}

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

type HotkeyCallback = (event: KeyboardEvent) => void

Hotkey

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'

SpecialCodes

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
  '`': 192
  '[': 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
}

Aliases

interface Aliases {
  break: 'pause'
  cmd: 'meta'
  command: 'meta'
  ctrl: 'control'
  del: 'delete'
  down: 'arrowdown'
  esc: 'escape'
  left: 'arrowleft'
  // will respond to the `command` key on a mac and
  // to the `control` key everywhere else
  mod: 'meta' | 'control'
  option: 'alt'
  return: 'enter'
  right: 'arrowright'
  space: ' '
  spacebar: ' '
  up: 'arrowup'
  windows: 'meta'
}

Modifiers

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