React hook for handling keyboard shortcuts, offering a customizable and platform-aware solution, supporting global and scoped modes.
npm install @bigbinary/neeto-hotkeysThe neeto-hotkeys package provides the useHotKeys hook, a versatile utility
for managing hotkeys in an application. This hook allows you to define specific
hotkey combinations and associate them with corresponding handler functions. The
associated handler is invoked upon pressing the configured hotkey(s), enabling
you to execute actions in response to keyboard input.
``zsh`
yarn add @bigbinary/neeto-hotkeys
- hotkey: A string specifying the hotkey(s) to listen for. Hotkeys can besequential
defined in three formats: , simultaneous & single.
1. Sequential: Any keys separated by a space are considered sequential. The
handler is invoked when the user presses the keys in sequence. For
example, s r means that when the user presses s followed by an r thehandler
corresponding will be invoked.command+shift+r
2. Simultaneous: Simultaneous hotkeys require all specified keys to be
pressed at the same time to trigger the handler. For example,
means that when command, shift, r are pressed atr
the same time the handler will be invoked.
3. Single: As the name indicates, this denotes single keys like , k,return
etc. Whenever r is pressed its corresponding handler will be
called.
The hotkey should be in MacOS format, the hook will take care of converting it
to the users platform(eg: command -> ctrl for windows).
If we want to bind multiple hotkeys to the same handler we can pass in an
array like so useHotkeys(['a', 'b'], handler).
- handler: The function that should be invoked when the hotkey is pressed.
Handler will receive the original key event. This can be used to stop theevent.preventDefault()
default browser action like so .
- config: A config object which has 3 properties mode, unbindOnUnmount &enabled
.
1. mode: The available values for mode are default, global & scoped.div
- default: It is the default mode. Handlers will only be called if the
user is outside of a textarea, input, or select element.
- global: Handlers will be fired even if the user is inside form elements
like textarea.
- scoped: It is used for scoping a hotkey to a DOM element. You can use
this option if you want to invoke the handlers only if the user is
focused in a specific , button, textarea and so on. When thisref
mode is set the hook will return a , you need to attached thatref
to the element to which you need to scope the hotkey.true
2. unbindOnUnmount: By default its value will be . If you don't want afalse
handler to be unregistered when a component is unmounted then set the
value to .true
3. enabled: By default its value will be . Setting this to false willdocument
not register the hotkey.
4. document: This is an optional property. If you want to listen for hotkeys
on an external document (e.g., an iframe), pass the reference of that
document using the property in the config object. If you do
not provide this property, the hook will listen for hotkeys on the current
document by default.
- inputRef: A ref which needs to be attached to the input element to be
listened to.
Following illustrates the usage of useHotKeys hook in implementing shortcut
for Sidebar opening.
`jsx
import useHotKeys from "@bigbinary/neeto-hotkeys";
// openSidebar function will only be called if the user is focused inside the textarea and performs the key combination.
const ref = useHotKeys("command+shift+r", openSidebar, {
mode: "scoped",
});
return (
Hotkeys are a fundamental aspect of many applications, enhancing user efficiency
and interactivity. The useHotKeys hook simplifies the implementation of these
hotkeys by allowing you to specify the hotkey combinations in various formats,
associated handlers, and configuration options.