You can change the active state of a scope using the disableScope, enableScope and toggleScope functions
returned by the useHotkeysContext() hook. Note that you have to have your app wrapped in a <HotkeysProvider> component.
set the hotkeys you want the hook to listen to. You can use single or multiple keys, modifier combinations, etc. This will either be a string or an array of strings. To separate multiple keys, use a comma. This split key value can be overridden with the splitKey option.
This is the callback function that will be called when the hotkey is pressed. The callback will receive the browsers native KeyboardEvent and the libraries HotkeysEvent.
options
Options
optional
{}
Object to modify the behavior of the hook. Default options are given below.
dependencies
DependencyList
optional
undefined
If omitted, the latest callback is used on every render. An empty array ([]) keeps the initial callback. With dependencies, the callback is memoised and updated when a dependency changes, much like useCallback in React. Include every outside variable used by the callback in the array.
Options
All options are optional and have a default value which you can override to change the behavior of the hook.
Option
Type
Default value
Description
enabled
boolean or (keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => boolean
true
This option determines whether the hotkey is active or not. It can take a boolean (for example a flag from a state outside) or a function which gets executed once the hotkey is pressed. If the function returns false the hotkey won't get executed and all browser events are prevented.
enableOnFormTags
boolean or FormTags[]
false
By default, hotkeys are disabled when a form element is focused. This prevents accidental triggering while the user is typing. Set to true to enable on all form tags, or pass an array of specific tags (e.g. ['input', 'textarea', 'select'])
enableOnContentEditable
boolean
false
Enable hotkeys on elements with the contentEditable attribute set to true
splitKey
string
+
Character that joins keys within a combination (e.g. shift+a). Change this if you need to listen for the + key itself
delimiter
string
,
Character that separates different hotkey combinations mapped to the same callback (e.g. ctrl+a, shift+b)
scopes
string or string[]
*
With scopes you can group hotkeys together. The default scope is the wildcard * which matches all hotkeys. Use the <HotkeysProvider> component to change active scopes.
keyup
boolean
false
Trigger the callback on the browser's keyup event
keydown
boolean
true
Trigger the callback on the browser's keydown event. Set both keyup and keydown to true to trigger on both events
preventDefault
boolean or (keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => boolean
false
Prevent the browser's default behavior for the matched keystroke. Useful for overriding shortcuts like meta+s. Note: some browser shortcuts (e.g. meta+w) cannot be overridden
description
string
undefined
Human-readable description of what the hotkey does. Useful for building help panels
useKey
boolean
false
Listen to the produced character instead of the physical key code
ignoreModifiers
boolean
false
Ignore modifier keys when matching hotkeys
sequenceTimeoutMs
number
1000
Time window in milliseconds for sequential hotkeys
Overloads
The hooks call signature is very flexible. For example if you don't need to set any special options you can use the dependency
array as your third parameter:
Note: Wrap your components in a HotkeysProvider to access active scopes and registered hotkeys. Outside a provider, the hook returns empty arrays and no-op functions.
Checkout this repo, run yarn or npm i and then run the test script to test the behavior of the hook.
Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request
License
Distributed under the MIT License. See LICENSE for more information.