npm:@elbstack/react-hotkeys

README

React HotKeys

A declarative library for handling hotkeys and focus areas in React applications.

Feature Overview

Minimal and declarative API
Named hotkeys for easy customization
Intuitive key commands thanks to Mousetrap
Tree based priority - the deepest focused handler wins
Easy-to-use HOC available.

Usage

Key map

import {HotKeys} from 'react-hotkeys';

// Simple "name:key sequence/s" to create a hotkey map

const map = {
  'snapLeft': 'command+left',
  'deleteNode': ['del', 'backspace']
};

// Component with a key map

const App = React.createClass({
  render() {
    return (
      <HotKeys keyMap={map}>
        <div>
          <MyNode></MyNode>
          <MyNode></MyNode>
        </div>
      </HotKeys>
    );
  }
});

Handlers

import {HotKeys} from 'react-hotkeys';

/**
 * Component with hotkey handlers, which are only called when the component
 * is within the application's 'focus tree' and prevents cascading hotkeys from
 * being called
 */

const MyNode = React.createClass({
  render() {
    const handlers = {
      'deleteNode': this.deleteNode
    };

    return (
      <HotKeys handlers={handlers}>
        Node contents
      </HotKeys>
    );
  }
});

Install

CommonJS & ES6 Modules

react-hotkeys is available as a CommonJS or a ES6 Modules through npm or yarn. It uses NODE_ENV to determine whether to export the development or production build in your library or application.

It is expected you will use a bundling tool like Webpack or Uglify to remove the version of the bundle you are not using with each version of your application's code, to keep the library size to a minimum.

npm

npm install react-hotkeys --save

yarn

yarn add react-hotkeys

UMD

react-hotkeys as a UMD module is available on your CDN of choice.

Change 1.0.1 for the version that you would like to use.

Development build

<script crossorigin src="https://cdn.jsdelivr.net/npm/react-hotkeys@1.0.1/umd/react-hotkeys.js"></script>

<script crossorigin src="https://unpkg.com/react-hotkeys@1.0.1/umd/react-hotkeys.js"></script>

Minified production build

<script crossorigin src="https://cdn.jsdelivr.net/npm/react-hotkeys@1.0.1/umd/react-hotkeys.min.js"></script>

<script crossorigin src="https://unpkg.com/react-hotkeys@1.0.1/umd/react-hotkeys.min.js"></script>

Bower

Bower support was removed in v1.0.0, but those who already rely on earlier versions of react-hotkeys through Bower can continue to do so using the following command:

bower install react-hotkeys@0.10.0

The Bower version of the package will not be supported going forward (including fixing any outstanding issues).

Defining Hot Keys

react-hotkeys uses key maps to separate defining keyboard shortcuts from the actions that they trigger. This allows adding or changing hot keys in the future, without having to also update the actions in many places across your application.

Hotkey maps are simple JavaScript objects, where the keys are the names of the actions triggered and the values are a Mousetrap-supported key sequence that must be activated in order to trigger the action.

const keyMap = {
  'deleteNode': 'del',
  'moveUp': 'up'
};

Alternative Hotkeys

You can specify multiple keys that will trigger the same action using arrays:

const keyMap = {
  'deleteNode': ['del', 'backspace'],
  'moveUp': ['up', 'w']
};

Key Combinations & Sequences

// Single key sequence
'4'

// Special single key sequence (ie. shift is handled automagically)
'?'

// Combination sequence
'command+shift+k'

// GMail style sequences
'up down left right'

Binding to Special Keys

Modifier keys: shift, ctrl, alt/option, command/meta

Special keys: backspace, tab, enter, return, capslock, esc, escape, space, pageup, pagedown, end, home, left, up, right, down, ins, del, and plus

Full Reference

Refer to Mousetrap's documentation for an exhaustive list of supported shortcuts and sequences.

Specifying Key Event

react-hotkeys tries to automatically determine the best key event (usually keypress) to monitor based on the key sequence provided.

The object syntax and action attribute lets you explicitly set which key event you wish to bind to:

const keyMap = {
  'contract': 'alt+down',
  'commandDown': {sequence: 'command', action: 'keydown'},
};

The full list of valid key events is: keypress, keydown, and keyup.

Defining Handlers

Key maps trigger named actions when matching keys are pressed - but do not define any behaviour. Handlers are the functions called to handle when a matching action is triggered and define how your application should respond.

Handlers may be defined in the same <HotKeys /> component as the key map:

import {HotKeys} from 'react-hotkeys';

const keyMap = {
    moveUp: 'up',
}

const handlers = {
  'moveUp': (event) => console.log('Move up hotkey called!')
};

<HotKeys keyMap={keyMap} handlers={handlers}>
  <input />
</HotKeys>

Or in any descendant of the <HotKeys /> component that defines the key map:

import {HotKeys} from 'react-hotkeys';

const keyMap = {
    moveUp: 'up',
}

const handlers = {
  'moveUp': (event) => console.log('Move up hotkey called!')
};

<HotKeys keyMap={keyMap}>
  <div>
   <HotKeys handlers={handlers}>
     <input />
   </HotKeys>
  </div>

  <div>
   <input />
  </div>
</HotKeys>

Hard Sequence Handlers

You can also explicitly define sequences as handlers in case you want a hard-override.

// If no named hotkey 'up' exists we assume it is a key sequence
const handlers = {
  'up': (event) => console.log('up key called')
};

Triggering Hot Keys

Key handlers are only called under the following conditions (all must be true):

One of the descendents of a <HotKeys /> component that defines handlers is currently in focus (or the focused prop is true)
Either that <HotKeys /> component, or one of its ancestors that is a <HotKeys /> component, defines a keyMap that has a sequence that matches the keys being pressed
The <HotKeys /> component that defines handlers has a handler that matches the action being triggered
A more deeply nested <HotKeys /> component's handler has not already been called

A more exhaustive enumration of react-hotkeys behaviour can be found by reviewing the test suite.

Elements must be in focus

In order for a hot key to be triggered, an element that is a descendent of the <HotKey /> component that defines handlers must be in focus. It is not enough to have a descendent element of a <HotKey /> that defines a keyMap in focus - it must be one that defines handlers. See Managing focus in the browser for more details.

Simulating an element's focus

You can cause a <HotKey /> with a handlers prop to behave as if one of its descendents is currently focused (and call any matching handlers) using the focused prop:

<HotKeys keyMap={this.keyMap} handlers={this.handlers} focused>
  <input />
</HotKeys>

Hot Key Action Propagation

Actions start at the <HotKeys /> component that is the the closest ancestor to the element in focus and only propagate until they are handled the first time: handlers in parent <HotKeys /> components will not be called if a child has already handled it.

Managing focus in the browser

Focusable elements

If you wish to support HTML4 you are limited to the following focusable elements:

<a>
<area>
<button>
<input>
<object>
<select>
<textarea>

HTML5 allows any element with a tabindex attribute to receive focus.

Tab order

If no elements have a tabindex in a HTML document, the browser will tab between focusable elements in the order that they appear in the DOM.

If there are elements with tabindex values greater than zero, they are iterated over first, according their tabindex value (from smallest to largest). Then the browser tabs over the focusable elements with a 0 or unspecified tabindex in the order that they appear in the DOM.

If any element is given a negative tabindex, it will be skipped when a user tabs through the document. However, a user may still click or touch on that element and it can be focused programmatically (see below). By default, <Shortcuts> elements are given a tabindex of -1.

Programmatically manage focus

To programmatically focus a DOM element, it must meet two requirements:

It must be a focusable elements
You must have a reference to it

You can get a reference to an element using React's ref property:

class MyComponent extends Component {

    componentDidUpdate(prevProps) {

        if(!prevProps.isFocused && this.props.isFocused) {
            this._container.focus();
        }

    }

    render() {
        return (
            <div ref={ (c) => this._container = c } >
                My focusable content
            </div>
        )
    }

}

Get the element currently in focus

You can retrieve the element that is currently focused using the following:

document.activeElement

Troubleshooting & Gotchas

Not compatible with lodash-webpack-plugin

There is some suggestion that react-hotkeys is not compatible with lodash-webpack-plugin. If you are experiencing issues where none of your handlers are being called and are using this webpack plugin, please try disabling it.

Blue border appears around children of HotKeys

react-hotkeys adds a <div /> around its children with a tabindex="-1" to allow them to be programmatically focused. This can result in browsers rendering a blue outline around them to visually indicate that they are the elements in the document that is currently in focus.

This can be disabled using CSS similar to the following:

div[tabindex="-1"]:focus {
    outline: 0;
}

Support

Please use Gitter to ask any questions you may have regarding how to use react-hotkeys.

If you believe you have found a bug or have a feature request, please open an issue.

Stability & Maintenance

react-hotkeys is considered stable and already being widely used (most notably Lystable and Whatsapp).

It has a non-comprehensive test suite.

In November 2017, responsibility for maintaining react-hotkeys has changed hands. The new group of contributors will be working towards improving performance and providing additional functionality rather than having any breaking changes.

Contribute, please!

If you're interested in helping out with the maintenance of react-hotkeys, make yourself known on Gitter, open an issue or create a pull request.

All contributions are welcome and greatly appreciated - from contributors of all levels of experience.

Collaboration is loosely being coordinated across Gitter and Projects.

Roadmap

The product roadmap is being currently being tracked in Projects, but is largely focused on improving performance, code quality and adding extra features to meet common requirements.

Using GitHub Issues

Use the search feature to check for an existing issue
Include as much information as possible and provide any relevant resources (Eg. screenshots)
For bug reports ensure you have a reproducible test case
- A pull request with a breaking test would be super preferable here but isn't required

Submitting a Pull Request

Squash commits
Lint your code with eslint (config provided)
Include relevant test updates/additions

Authorship

All credit, and many thanks, goes to Chris Pearce for the inception of react-hotkeys and all versions before 1.0.0.

As of version 1.0.0, Aleck Greenham is actively maintaining react-hotkeys. Please be patient while he gets up to speed.

Thanks

Thanks to @ccampbell for Mousetrap

Usage no npm install needed!