Declarative hotkey and focus area management for React
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.
Upgrading from v1.*?
This release is the same as the
v2.0.0-pre9
and these release notes contain a summary of the changes moving from v1.* tov2.0.0
.Upgrading from v2.0.0-pre*?
Ignore this set of release notes, and follow the notes for each each pre-release starting from the version you are using, up to
v2.0.0-pre9
.
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.
This was an internal part of react-hotkeys
and is no longer used, and so it does not makes sense to continue to provide it.
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 provide it.
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);
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 (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
});
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.
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.
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.
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
}
});
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
});
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
});
You can now use browser key names when defining your sequences, in addition to Mousetrap's name for the keys.
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.
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
hotKeys
props 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>
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>
<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).
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 <IgnoreKeys/>
component:
import {IgnoreKeys} from 'react-hotkeys';
<IgnoreKeys>
/**
* Children that, when in focus, should have its key events ignored by
* react hotkeys
*/
</IgnoreKeys>
The <ObserveKeys />
component (and corresponding withObserveKeys
method to avoid wrapper div) are for defining white-list exceptions to the the default ignoreEventsCondition
<ObserveKeys only={'Escape'}>
<input
autoFocus
onChange={({target: {value}}) => this.setState({ filter: value })}
value={filter}
placeholder='Filter'
/>
</ObserveKeys>
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.
It's now possible to generate a list of hotkeys for the application to display to the user.
Thanks to #124, <ReactHotkeys />
now accepts an innerRef
prop:
class MyComponent extends Component {
componentDidMount() {
this._container.focus();
}
render() {
return (
<HotKeys innerRef={ (c) => this._container = c } >
My focusable content
</div>
)
}
}
You can now specify name, description and groups for key maps #154 (More info)
SHOW_DIALOG: {
name: 'Display keyboard shortcuts',
sequence: 'shift+?',
action: 'keyup'
}
You can now define custom key codes for WebOS and other environments (#156) (More info)
import {configure} from 'react-hotkeys';
configure({
customKeyCodes: {
10009: 'BackTV'
}
})
You can now set dynamic key maps at runtime (#158) (More info)
cmd
is now an accepted alias for Command
/Meta
keyThe 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 in your app.
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.
Some improved and additional optimisations have been implemented as part of this release.
allowCombinationSubmatches
is now ignored when the Cmd
key is pressed down (submatches are always allowed when Cmd
is pressed). This is to fix the following bug.Cmd
(Meta
) key (e.g.cmd+1
-> cmd+2
without releasing Cmd
) #201ignoreRepeatedEventsWhenKeyHeldDown
configuration option. SHOW_DIALOG: {
name: 'Display keyboard shortcuts',
sequence: 'shift+?',
action: 'keyup'
}
import {configure} from 'react-hotkeys';
configure({
customKeyCodes: {
10009: 'BackTV'
}
})
useState
now work correctly (#182, #196)cmd
acting as if those keys were still pressed down after they've been released (#183)except
or only
options of ObserveKeys
and IgnoreKeys
(#198)react-hotkeys
now ignores key combination submatches #186 by default.
This resolves the issue of when an application has a context-dependent action, bound to a short key combination (e.g.?
) and a longer global action bound to a longer key combination (e.g. shift+?
), and the longer key combination is hidden behind the shorter one and never triggered whenever a child of the <HotKeys/> component that defines the shorter combination is in focus (#161, #181, #175).
If you would like the old behaviour, you can re-enable submatches with the allowCombinationSubmatches
configuration option:
configure({
allowCombinationSubmatches: true,
})
For a full description of what this change means, and the tradeoffs, see the How combinations and sequences are matched section of the Readme.
A new root
prop is now available for HotKeys
that allows placing HotKeys
components at the root of the app without actually defining any key maps or handlers, to ensure all key events are recorded (#188):
<HotKeys root>
//... application
</HotKeys>
For details of when you may want to use this, see the React Hotkeys thinks I'm holding down a key I've released section of the readme.
GlobalHotKeys
components now report key events that may have been missed by HotKeys
, to avoid hanging key combinations when an action handler changes focus outside of the part of the React app below the highest HotKeys
component.
Again, you can see the React Hotkeys thinks I'm holding down a key I've released section of the readme for more details.
This release still has a number of known issues, but hopefully it will go some way to addressing some of the issues people are experiencing.
ref
prop now has correct TypeScript type (Thanks @natew!) #168ignoreEventsCondition
now has correct argument TypeScript definition (Thanks @taromurao!) #170Delete
and Backspace
(and the variant del
) are no longer treated as aliases for one another. You will need to bind handlers to both, if you want to maintain backwards compatibility. #145, #159<HotKeysIgnore />
component has been renamed to <IgnoreKeys />
withHotKeysIgnore
has been renamed to withIgnoreKeys
@private
annotationscmd
is now an accepted alias for Command
/Meta
key<ObserveKeys />
component (and corresponding withObserveKeys
method to avoid wrapper div) for defining white-list exceptions to the the default ignoreEventsCondition
<ObserveKeys only={'Escape'}>
<input
autoFocus
onChange={({target: {value}}) => this.setState({ filter: value })}
value={filter}
placeholder='Filter'
/>
</ObserveKeys>
<HotKeys>
passing the component
prop down to its childrenIt's now possible to generate a list of hotkeys for the application to display to the user.
Thanks to #124, <ReactHotkeys />
now accepts an innerRef
prop:
class MyComponent extends Component {
componentDidMount() {
this._container.focus();
}
render() {
return (
<HotKeys innerRef={ (c) => this._container = c } >
My focusable content
</div>
)
}
}
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.
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.
This was an internal part of react-hotkeys
and is no longer used, and so it does not makes sense to continue to supply.
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.
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);
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 (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
});
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.
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.
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.
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
}
});
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
});
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
});
You can now use browser key names when defining your sequences, in addition to Mousetrap's name for the keys.
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.
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
hotKeys
props 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>
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>
<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).
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>
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.
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.
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.
Some improved and additional optimisations have been implemented as part of this release.