react-keyboard-shortcuts-eleung
v1.1.7
Published
A declarative library for handling hotkeys based on explicit priority in React applications
Downloads
10
Maintainers
Readme
A declarative library for handling hotkeys based on explicit priority in React applications.
Feature Overview
- Minimal and declarative API
- Intuitive key commands thanks to Mousetrap
- Explicit priority based event handling (see more later)
Inspired by
Difference in event handling
Most hotkey or shortcut managing libraries follow the focus tree for event handling. Meaning that the element that has focus tries its handler and if it does not process the hotkey allows its parent to try and so on up do the document root. However, there are many cases where one element has focus but another has the handler but they are not in each other linage.
+ root
|
+---+--------+
| |
| |
+---+---+ +
| | Text
| |
+ +
Back Next
For example, let say that you have a text element that currently have focus but you want the hotkeys alt+b and alt+n to work for the back and next buttons. These two buttons are not in the focus tree but are cousins. You could in those other libraries set the handlers on the root, but that often means that the root either has to have those same redux actions or has to have a reference to the next and back button to make those handlers work. Both are messy. Instead react-keyboard-shortcuts allows the Back and Next button to register hotkeys that work globally (regardless of what element has focus).
When the Back and Next buttons mount their hotkeys are register. When they unmount their hotkeys are unregister (via a higher-order-component). Also if two or more components want to have handlers for the same sequence they each provide a priority explicitly that determines who gets first chance (think of it like the z-index for css).
Install
npm
npm install react-keyboard-shortcuts
yarn
yarn add react-keyboard-shortcuts
Usage
Easy Example
import React from 'react'
import {hotkeys} from 'react-keyboard-shortcuts'
class NextButton extends React.PureComponent {
static propTypes = {
onClick: PropTypes.func.isRequired,
}
hot_keys = {
'alt+n': { // combo from mousetrap
priority: 1,
handler: (event) => this.props.onClick(),
},
}
render () {
return (
<button onClick={this.props.onClick}> Next</button>
)
}
}
export default hotkeys(NextButton)
API
hotkeys([component], [options = {}])
- options:
hot_key_property_name
- defaults tohot_keys
- options:
- handler ** return false if you do not want it to propagate to the next priority handler
Notes
- If using with redux connect do the hotkey first then connect
connect(mapStateToProps, actions)(hotkeys(NextButton))
- hotkeys will work even in form elements (not Mousetrap's default behavior)
Extras
hotkey_display just a helper for display the keys to users
import {hotkey_display} from 'react-keyboard-shortcuts'
const tooltip = hotkey_display('alt+n') // on a mac this will return 'option'
const tooltip = hotkey_display('meta+n') // on a mac this will return '⌘'
Thanks
Thanks to @ccampbell for Mousetrap
License
MIT