Neverending Package Mountain

    @react-hook/hotkey
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.0 • Public • Published

    useHotkey()

    Bundlephobia Types NPM Version MIT License

    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

    Install

    npm i @react-hook/hotkey

    DownloadsWeekly Downloads

    970

    Version

    3.1.0

    License

    MIT

    Unpacked Size

    62.6 kB

    Total Files

    20

    Last publish

    Collaborators

    • jaredlunde