Migrate from 3.x to 4.x

There are a few breaking changes in 4.x. This guide will help you migrate your code.

API changes

useHotkeys hook

filter

The filter option no longer exists, it has been merged with the enabled option. enabled now takes a "trigger". A trigger is either a boolean or a function that returns a boolean. If the trigger is a function, it will be called with the key event as the first argument. If the trigger returns true, the hotkey will be executed. If it returns false, the hotkey will be ignored.

Old splitKey behavior is now found under combinationKey

splitKey has been renamed to combinationKey to avoid confusion with a new feature that actually addresses the split key.

When defining complex hotkeys, you have three parts: The keys, the key that combines keys (e.g. ctrl + a - which is now known as the combinationKey), and the key that splits the string into multiple key combinations (e.g. ctrl , a - which is the correct splitKey).

So in your old code you just have to replace splitKey with combinationKey and you are good to go.

But as a new feature, you can now define a splitKey. This is useful if you want to define a hotkey that uses a , in the key combination, but you want multiple key combinations to trigger the same callback.

dependencies are now properly typed

Beforehand the dependencies option was typed as any[]. This has been changed to DependencyList which is the correct type for a react hook dependency list.

cmd and command keys are no longer supported

If you are using those keys, you have to replace them with meta.

enableOnTags is now renamed to enableOnFormTags

The functionality is still the same, but the name is more accurate.

Under the hood

Prior to version 4, we used the hotkeys.js library to handle keyboard shortcuts. Since this is handling the keyboard shortcuts globally, we decided to drop the dependency and implement our own solution. This means that there are a few changes in behavior. We also used that opportunity to clean up the API a bit. With the new implementation came a lot of bug fixes that we previously couldn't fix ourselves. We hope that this will make the library more stable and easier to use and maintain.