use-keyboard-shortcuts

An intuitive React hook to enable keyboard shortcuts.

Quick Example

  useKeyboardShortcuts([
    { keys: ["ctrl", "a"], onEvent: event => alert("ctrl + a was pressed") },
    { keys: ["shift", "b"], onEvent: event => alert("shift + b was pressed") },
    { keys: ["Tab"], handleNext },
    { keys: ["Esc"], handleClose },
    { keys: ["Enter"], handleSubmit, preventDefault: false },
  ])

  useKeyboardShortcuts(
    [{ keys: ["ctrl", "shift"], onEvent: () => alert('ctrl + shift + scroll is active') }],
    true,
    [],
    "mousewheel"
  )
}

Features

• Easy to use
• Typescript support
• Multiple shortcuts registered at the same time
• Support for special keys: Shift, Ctrl (command on Mac), Alt (option on Mac).
• Support for keydown and mousewheel events
• Prevents mature propagation. This means that if you have a shortcut for ctrl + a and ctrl + shift + a in the same hook, then the action for ctrl + a will not trigger when pressing ctrl + shift + a.

Install

$ npm install --save use-keyboard-shortcuts
$ yarn add use-keyboard-shortcuts

Usage

import React from "react"
import useKeyboardShortcuts from "use-keyboard-shortcuts"

const Example = () => {
  const [isOpen, setIsOpen] = React.useState(false)

  useKeyboardShortcuts([
    { keys: ["ctrl", "a"], onEvent: event => alert("ctrl + a was pressed") },
    { keys: ["Esc"], onEvent: () => setIsOpen(false) },
  ])

  return <div>...</div>
}

Arguments

| Argument (in order) | Type | Default | Description | | ------------------- | -------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | | shortcuts | Shortcut[] | undefined | Array of Shortcut-objects that should listen to the specified dependencies and eventType. See Shortcut object-section. | | active | boolean | true | Disables or enables all shortcuts. | | dependencies | any[] | [] | List dependencies of the shortcuts | | eventType | "keydown"/"mousewheel" | "keydown" | Wether it should listen for keyboard or mouse scroll events |

Shortcut object

| Key | Type | Description | | ---------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | keys | string[] | Combination of keys that needs to be pressed to trigger onEvent(). | | onEvent | function(event) | Action for when combination in keys are pressed. | | disabled | boolean | Used to disable a shortcut in particular |

Example

See the example-folder for an extended example of how to use this hook with the mousewheel event type.

License

MIT � SAITS