A declarative library for handling hotkeys and focus areas in React applications.
react-hotkeys is currently seeking new maintainers.
- 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.
Play with a live example of react-hotkeys!
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>
);
}
});
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>
);
}
});
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 install react-hotkeys --save
yarn add react-hotkeys
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.
<script crossorigin src="https://cdn.jsdelivr.net/npm/[email protected]/umd/react-hotkeys.js"></script>
<script crossorigin src="https://unpkg.com/[email protected]/umd/react-hotkeys.js"></script>
<script crossorigin src="https://cdn.jsdelivr.net/npm/[email protected]/umd/react-hotkeys.min.js"></script>
<script crossorigin src="https://unpkg.com/[email protected]/umd/react-hotkeys.min.js"></script>
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 [email protected]
The Bower version of the package will not be supported going forward (including fixing any outstanding issues).
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'
};
You can specify multiple keys that will trigger the same action using arrays:
const keyMap = {
'deleteNode': ['del', 'backspace'],
'moveUp': ['up', 'w']
};
// 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'
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
Refer to Mousetrap's documentation for an exhaustive list of supported shortcuts and sequences.
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
.
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>
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')
};
Key handlers are only called under the following conditions (all must be true):
- One of the descendents of a
<HotKeys />
component that defineshandlers
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 akeyMap
that has a sequence that matches the keys being pressed - The
<HotKeys />
component that defineshandlers
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.
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.
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>
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.
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.
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
.
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>
)
}
}
You can retrieve the element that is currently focused using the following:
document.activeElement
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.
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;
}
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.
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.
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.
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.
- 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
- Squash commits
- Lint your code with eslint (config provided)
- Include relevant test updates/additions
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 maintained react-hotkeys
.
react-hotkeys is currently seeking new maintainers.
Thanks to @ccampbell for Mousetrap