Keyboard control

An easy way to bind actions to a keyboard key combinations

In case you need to bind some keyboard keys or combinations of them to perform certain actions in your app, this component aims to provide a fast and reliable way to do so.

You don’t need to create and remove event listeners by yourself every time – event listeners will be created when this component is mounted, and removed once it’s unmounted. This also means that, according to your needs, you can control binding of keyboard keys by simply inserting and removing component with v-if conditional logic.

All you need to provide is an object with keyboard keys and methods that should be called when those keys are pressed.

Although you need to include it in your other components, this component doesn’t render anything, it will just create keydown event listeners and remove them once it’s unmounted.

Usage suggestions

Before we move on to the examples, please read the recommended use of keyboard in our apps. We strive to provide the best user experience for our users, and so do browsers, which have their own shortcuts and actions performed with certain key combinations that users may be used to, so hijacking keyboard can be annoying and counter productive for them, especially if you are preventing the browser’s default behavior.

• Do not bind single keys (letters and numbers especially) to perform some action! However, if you really must do it, set prevent to false so you don’t interfere with normal keyboard use. (Example: binding key A and not setting prevent to false will prevent user from entering the letter a in inputs)
• When using key combos, make sure to bind maximum 3 keys, 2 is preferable. (Example: Ctrl+Alt+Shift+F1 is too much keys)
• Make sure that key combination that you’re using isn’t already doing something in browser, and if it is the case, set prevent to false. You can read on some of the common keyboard shortcuts in Chrome here. Of course, you probably won’t be able to avoid the existing shortcuts in browser completely, so it’s a matter of balance which you’re going to prevent, and which you will not. (Example: Ctrl+J is a key combination that opens Downloads in Chrome and users will expect it to also work in our apps)
• If possible, create your shortcuts so they in some way remind users of the action that will be performed. (Example: Ctrl+M opens the main menu)

Binding single keys or key combinations

When you import <bdn-keyboard-control> component, you will need to provide a key map as an object. Keys in this object will be your keys, and value is an anonymous function that calls a method in your component.

If you want to bind a key combination, separate your keys with space.

It doesn't matter which case you use, ctrl m, Ctrl M and ctrl M are the same thing.

Note

You cannot bind Ctrl, Alt or Shift as single keys, those will work only in combination with other keys. Also, you cannot bind more than one action key (for example, you can’t use combination Ctrl+M+N).

Check out the example below – we will bind different keys and key combinations to alert what we just pressed.

This component doesn't insert anything in DOM.

Try pressing F1, F2, Shift+M or Ctrl+L

Not preventing default behavior

By default, keys that we bind will prevent default behavior in browsers. In case we want to change that, we need to make some changes to our key map object.

Take a look at the example below.

Note

Not all key combinations can be prevented, only those that are in use in browsers. For example, you cannot prevent behavior of Ctrl+Escape key combination, as this is at OS level (opens Start menu in Windows 10).

This component doesn't insert anything in DOM.

Try pressing Ctrl+K - after you close the alert, it should opent search bar in Chrome

Blocking the same key

In some cases, you may have multiple <bdn-keyboard-control> components with the same key, performing different actions. By default, all events added in event queue will be performed in order they were attached to window object, for example, and there’s no certain way to know this order or stop events from firing at some point that works out of the box.

Keyboard control goes around this by keeping count on the loaded components and bound keys, so if you add prop prevent-same-key it will perform action that exists on the same key only in the last loaded component.

For example, you have a form that is cleared when you press the Escape key, but and some point while filling the form you need to show a modal which you also want to close with escape button. Default behavior here would be that when that modal is opened, pressing the Escape key would first clear the form, and only then close the modal. But if you add prop prevent-same-key to keyboard control component that’s in your modal, then only modal will close, its keyboard-control component will be unmounted and only pressing Escape again would clear the form.

Check the example below – press Escape, close alert and then click on the button that will load another keyboard control component and then press Esc again.

This component doesn't insert anything in DOM.

Try pressing Escape

Props reference

Prop	Type	Default	Accepts	Description
key-map	Object	{}	Object	A map of bound keys and actions they perform when detected
prevent-same-key	Boolean	false	true/false	Prevents the previously loaded keyboard control components to fire the action on duplicate key