React HotKeys
A declarative library for handling hotkeys and focus areas in React applications.
See Exploring HotKeys and focus in React for an introductory look into the problems we're trying to solve or if you're eager to get going check out the Getting Started guide!
1.0.0
!
NOTE: This project is still in it's development stages. While I'm pretty confident on the API you should expect breaking changes on minor version upgrades until Quick Example
import {HotKeys} from 'react-hotkeys';
// Simple "name:key sequence/s" to create a hotkey map
const map = {
'snapLeft': 'command+left',
'deleteNode': ['del', 'backspace']
};
// Create a root component with the hotkey map
const App = React.createClass({
render() {
return (
<HotKeys keyMap={map}>
<div>
<Node></Node>
<Node></Node>
</div>
</HotKeys>
);
}
});
// Create a component with hotkey handlers - handlers only called when component is within
// the applications 'focus tree' and prevents cascading hotkeys from being called
const Node = React.createClass({
render() {
const handlers = {
'deleteNode': this.deleteNode
};
return (
<HotKeys handlers={handlers}>
Node contents
</HotKeys>
);
}
});
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
Install
npm install react-hotkeys
or use the old-skool UMD packaged library found in /build/global.
Documentation
The Getting Started guide is probably a good first point of call!
You can find full docs in the /docs folder and generated api docs in /docs/api.
You may also find various examples by loading the static /examples/index.html file.
Support
See "Using GitHub Issues" under "Contribute" below for most things but feel free to jump on Gitter or give me a shout (@chrisui) in the reactiflux Slack group!
Contribute
Awesome! Contributions of all kinds are greatly appreciated. To help smoothen the process we have a few non-exhaustive guidelines to follow which should get you going in no time.
Using GitHub Issues
- Feel free to use github issues for questions, bug reports, and feature requests
- 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
TODO List
- Delegate hotkeys to root handler (Rather than mousetrap instance for each)
- Provide HoC API
- Write tests
- Generate API docs
Thanks
Thanks to @ccampbell for Mousetrap
License
MIT