v2.0.0-pre1
Pre-release
This release represents a complete re-write of the internals and much of the interface of react-hotkeys. Mousetrap has been removed as a dependency, and instead react-hotkeys works on the top of the React SyntheticEvent events system.
This is a pre-release, so it not yet ready for use in production applications, but it does represent the future direction of the library.
Breaking Changes
__mousetrap__ is no longer available
Rather unsurprisingly, with the removal of Mousetrap, it's no longer possible to access the private Mousetrap instance to configure it. Many of the use-cases for needing to do so have been covered by API updates described below. If your use-case is not covered, however, please create a new issue.
HotKeyMapMixin has been removed
This was an internal part of react-hotkeys and is no longer used, and so it does not makes sense to continue to supply.
FocusTrap has been removed
Similar to HotKeyMapMixin, this was an internal part of react-hotkeys and is no longer used, and so it does not makes sense to continue to supply.
withHotKeys has been replaced
The old withHotKeys function has been repurposed and should not be used in the same way the old one was (more on this later). The old implementation is still available as deprecatedWithHotKeys, but it is no longer officially supported and will be removed in future versions.
Before:
import {withHotKeys} from 'react-hotkeys';
const ACTION_KEY_MAP = {
'changeColor': 'alt+c',
};
withHotKeys(ACTION_KEY_MAP)(HOCWrappedNode);After (suggested):
You can write your own function or HoC that supplies the same keyMap to a component passed to it.
import {HotKeys} from 'react-hotkeys';
const ACTION_KEY_MAP = {
'changeColor': 'alt+c',
};
function withActions(keyMap, Component) {
return function(props) {
return(
<HotKeys keyMap={keyMap}>
<Component {...props} />
</HotKeys>
);
}
}
deprecatedWithHotKeys(ACTION_KEY_MAP)(HOCWrappedNode);After (to restore old behaviour):
import {deprecatedWithHotKeys} from 'react-hotkeys';
const ACTION_KEY_MAP = {
'changeColor': 'alt+c',
};
deprecatedWithHotKeys(ACTION_KEY_MAP)(HOCWrappedNode);focused and attach props hav been removed
The focused and attach props were introduced as a way to bind keymaps that were either always active, or available outside of the React application. They are no longer needed with the introduction of GlobalHotkeys.
Before:
import {HotKeys} from 'react-hotkeys';
<HotKeys focused={true} attach={document} keyMap={keyMap} handlers={handlers}>
<div>
My content
</div>
</HotKeys>After:
import {GlobalHotKeys} from 'react-hotkeys';
<GlobalHotKeys keyMap={keyMap} handlers={handlers} />
<div>
My content
</div>Hard sequences are deprecated and turned off by default
Hard sequences (handlers associated to actions with names that are valid key sequence strings that implicitly define actions that are matched by the corresponding key sequence) are now deprecated and turned off by default. They can be re-enabled (at a performance penalty) using the enableHardSequences configuration option:
import {configure} from 'react-hotkeys';
configure({
enableHardSequences: true
});Default key event is now always keydown
react-hotkeys used to rely on the implicit behaviour of Mousetrap to guess the best key event based on the keys involved (this was, roughly speaking, keydown for non-modifier keys and keypress for modifier keys). Now by default, react-hotkeys will match hotkey sequences on the keydown event (or, more precisely: on the keydown event of the last key to complete the last combination in a sequence).
If you want to trigger a single action on a different key event, you can use the object syntax and the action attribute to explicitly set which key event you wish to bind to:
const keyMap = {
CONTRACT: 'alt+down',
COMMAND_DOWN: {sequence: 'command', action: 'keydown'},
};If you want to change the default key event for all hotkeys, you can use the defaultKeyEvent option of the configuration API.
Keypress events are now simulated for modifier keys
Before, you had to rely on Mousetrap guessing the best key event for your key combination (unless you explicitly defined an event) and if you bound to a key combination to a keypress event, it did not work (the browser does not emit these events for modifier keys).
react-hotkeys now simulates these events internally (they aren't emitted to the rest of your React components) so you do not have to worry about if your key combination includes a modifier key when binding to keypress.
This shouldn't affect most library consumers, but is listed as a breaking change as it can conceivably cause different behaviour for the same application code.
stopPropagation() is now observed
Because react-hotkeys now uses the React event system, event.stopPropagation() now works as expected. If you have event listeners in your React application that call event.stopPropagation() before the event reaches a <HotKeys /> or <GlobalHotkeys /> component that has a keyMap prop, react-hotkeys never sees it.
If you want to hide that a key has been pressed at all, you will need to capture all 3 of the keydown, keypress and keyup events.
Key events from input, select and textarea tags are ignored by default
If you were ignoring key events from certain inputs by overriding the stopCallback function on mousetrap as has been previously suggested, you no longer need to.
By default, all key events that originate from <input>, <select> or <textarea>, or have a isContentEditable attribute of true are ignored by react-hotkeys.
If this is not what you want for your application, you can modify the list of tags using the ignoreTags configuration option or if you need additional control, you can specify a brand new function using the ignoreEventsCondition configuration option.
Before:
const mousetrap = this.hotKeys.__mousetrap__;
mousetrap.__proto__.stopCallback = (e, element) => {
// Your custom logic here
};After:
(After you've confirmed the default function does not match your use-case):
import {configure} from 'react-hotkeys';
configure({
ignoreEventsCondition: function(event) {
const { target: element } = event;
// Your custom logic here
}
});stopPropagation() is called on events that are ignored
By default, react-hotkeys calls stopPropagation() on keyboard events that it ignores, at the first <HotKeys> component with a non-empty keyMap prop (or a hard sequence defined in the handlers prop, if hard sequences are enabled). This makes react-hotkeys more efficient, but may be hiding keyboard events from other key listeners you have in place in your React app.
You can disable this behaviour using the stopEventPropagationAfterIgnoring configuration option:
import {configure} from 'react-hotkeys';
configure({
stopEventPropagationAfterIgnoring: false
});Updates to keyMaps and handlers after focus are ignored by default
For performance reasons, by default react-hotkeys takes the keyMap and handlers prop values when <HotKeys> components are focused and when <GlobalHotKeys> components are mounted. It ignores all subsequent updates
to their values when these props change.
If you need the ability to change them while a <HotKeys> component is still in focus, or while <GlobalHotKeys> is still mounted, then you can pass the allowChanges prop, permitting this behaviour for the particular component.
import {HotKeys} from 'react-hotkeys';
class MyComponent extends React.Component {
render() {
return (
<HotKeys keyMap={keyMapThatChanges} handler={handlersThatChange} allowChanges>
</HotKeys>
);
}
}If you need to do this for all your <HotKeys> and <GlobalHotKeys> components, you can use the ignoreKeymapAndHandlerChangesByDefault option for the Configuration API. This should normally never be done, as it can have significant performance implications.
import {configure} from 'react-hotkeys';
configure({
ignoreKeymapAndHandlerChangesByDefault: false
});New features
Browser keynames are now supported in key sequence definitions
You can now use browser key names when defining your sequences, in addition to Mousetrap's name for the keys.
New withHotKeys HoC - a way to avoid rendering a wrapping div
If wrapping your component in a DOM-mountable node is not acceptable, or you need more control over how the react-hotkeys props are applied, then the new withHotKeys() HoC is available.
Simple use-case
The simplest use-case of withHotKeys() is to simply pass it your component class as the first argument. What is returned is a new component that will accept all of the same props as a <HotKey> component, so you can specify key maps and handlers at render time, for example.
The component you wrap must take responsibility for passing the
hotKeysprops to a DOM-mountable element. If you fail to do this, key events will not be detected when a descendant of the component is in focus.
import {withHotKeys} from 'react-hotkeys';
class MyComponent extends Component {
render() {
/**
* Must unwrap hotKeys prop and pass its values to a DOM-mountable
* element (like the div below).
*/
const {hotKeys, ...remainingProps} = this.props;
return (
<div { ... { ...hotKeys, ...remainingProps } } >
<span>My HotKeys are effective here</span>
{ this.props.children }
</div>
)
}
}
const MyHotKeysComponent = withHotKeys(MyComponent);
const keyMap = {
TEST: 't'
};
const handlers = {
TEST: ()=> console.log('Test')
};
<MyHotKeysComponent keyMap={ keyMap } handlers={ handlers }>
<div>
You can press 't' to log to the console.
</div>
</MyHotKeysComponent>Pre-defining default prop values
You can use the second argument of withHotKeys to specify default values for any props you would normally pass to <HotKeys />. This means you do not have to specify them at render-time.
If you do provide prop values when you render the component, these will be merged with (and override) those defined in the second argument of
withHotKeys.
import {withHotKeys} from 'react-hotkeys';
class MyComponent extends Component {
render() {
/**
* Must unwrap hotKeys prop and pass its values to a DOM-mountable
* element (like the div below).
*/
const {hotKeys, ...remainingProps} = this.props;
return (
<div { ... { ...hotKeys, ...remainingProps } } >
<span>My HotKeys are effective here</span>
{ this.props.children }
</div>
)
}
}
const keyMap = {
TEST: 't'
};
const handlers = {
TEST: ()=> console.log('Test')
};
const MyHotKeysComponent = withHotKeys(MyComponent, {keyMap, handlers});
/**
* Render without having to specify prop values
*/
<MyHotKeysComponent>
<div>
You can press 't' to log to the console.
</div>
</MyHotKeysComponent>New GlobalHotKeys component
<GlobalHotKeys> components match key events that occur anywhere in the document (even when no part of your React application is in focus). They replace the need for the focused and attach prop.
const keyMap = { SHOW_ALL_HOTKEYS: 'shift+?' };
const handlers = { SHOW_ALL_HOTKEYS: this.showHotKeysDialog };
<GlobalHotKeys keyMap={ keyMap } handlers={ handlers } /><GlobalHotKeys> generally have no need for children, so should use a self-closing tag (as shown above). The only exception is when you are nesting other <GlobalHotKeys> components somewhere in the descendants (these are mounted before their parents, and so are generally matched first).
New HotKeysIgnore component
If you want react-hotkeys to ignore key events coming from a particular area of your app when it is in focus, you can use the new <HotKeysIgnore/> component:
import {HotKeysIgnore} from 'react-hotkeys';
<HotKeysIgnore>
/**
* Children that, when in focus, should have its key events ignored by
* react hotkeys
*/
</HotKeysIgnore>How actions and handlers are resolved
Regardless of where <GlobalHotKeys> components appear in the render tree, they are matched with key events after the event has finished propagating through the React app (if the event originated in the React at all). This means if your React app is in focus and it handles a key event, it will be ignored by the <GlobalHotKeys> components.
The order used for resolving actions and handlers amongst <GlobalHotKeys> components, is the order in which they mounted (those mounted first, are given the chance to handle an action first). When a <GlobalHotKeys> component is unmounted, it is removed from consideration. This can get less deterministic over the course of a long session using a React app as components mount and unmount, so it is best to define actions and handlers that are globally unique.
It is recommended to use <HotKeys> components whenever possible for better performance and reliability.
You can use the autofocus attributes or programmatically manage focus to automatically focus your React app so the user doesn't have to select it in order for hot keys to take effect. It is common practice to place a
<HotKeys>component towards the top of your application to match hot keys across your entire React application.
New Configuration configuration API for global settings
The default behaviour across all <HotKeys> and <GlobalHotkeys> components is configured using the configure method.
configure() should be called as your app is initialising and before the first time you mount a
<HotKeys>component anywhere your app.
New comprehensive logging
react-hotkeys now provides comprehensive logging of all of its internal behaviour and allows setting one of 6 log levels.
The default level is warn, which provides warnings and errors only, and is generally sufficient for most usage. However, if you are troubleshooting an issue or reporting a bug, you should increase the log level to debug or verbose to see what is going on, and be able to communicate it concisely.
Optimizations
Some improved and additional optimisations have been implemented as part of this release.