nick-barth / vue3-keypress

Global keypress event handler component for Vue 3 applications.

⚠️ Breaking Changes with V4 ⚠️

Version 4 introduced breaking changes by making use of the Vue 3 composition API and dropping the component-based approach. Follow the guide below to setup the module following the new approach.

Vue Keypress

Want to capture keydown, keypress and keyup and events globally in Vue? Nothing easier than that.

The Vue Keypress Component let's you do just that.

Just add the component to the view/component that should start a global keypress handler. When the component gets destroyed, the global event handler also gets removed.

‼️ Using Vue 2?

This package only supports Vue 3.

For Vue 2 support, visit the lupas/vue-keypress package repository.

How to install?

yarn add vue3-keypress
// or
npm i vue3-keypress

How to use in your project?

Simple Example

<script>
import { useKeypress } from 'vue3-keypress'
import { ref } from 'vue'

setup() {
    const someSuccessCallback = ({ keyCode }) => {
        // doSomething
    }

    useKeypress({
        keyEvent: "keydown",
        keyBinds: [
          {
            keyCode: "down", // or keyCode as integer, e.g. 40
            success: someSuccessCallback,
          },
        ]
    })
}
</script>

Full Example

<script>
import { useKeypress } from "vue3-keypress";
import { ref } from "vue";

export default {
  components: {
    KeyBackground,
  },
  setup() {
    const pressedKeyCode = ref(null);
    const isSuccess = ref(false);
    const isActiveRef = ref(true);

    const someSuccessCallback = ({ keyCode }) => {
      isSuccess.value = true;
    };

    const someWrongKeyCallback = ({ event }) => {
      isSuccess.value = false;
    };

    const someAnyKeyCallback = ({ event }) => {
      pressedKeyCode.value = event.keyCode;
    };

    useKeypress({
      keyEvent: "keydown",
      keyBinds: [
        {
          keyCode: "left", // or keyCode as integer, e.g. 37
          modifiers: ["shiftKey"],
          success: someSuccessCallback,
          preventDefault: true, // the default is true
        },
        {
          keyCode: "right", // or keyCode as integer, e.g. 39
          modifiers: ["shiftKey"],
          success: someSuccessCallback,
          preventDefault: true, // the default is true
        },
      ],
      onWrongKey: someWrongKeyCallback,
      onAnyKey: someAnyKeyCallback,
      isActive: isActiveRef,
    });

    return {};
  },
};
</script>

Config

Variable	Type	Default	Possible Values	Description
keyEvent	String	'keyup'	keydown, keypress, keyup
keyBinds	KeyBind[]	[]	see below	Object containing infos about which keys are expected to be pressed.
isActive	Ref(Boolean)	false	true / false	Setups up a listener that activates/deactivates the keypress listener.
onWrongKey	Function	null		Callback that is triggered every time a key is pressed that is not in "keyBinds".
onAnyKey	Function	null		Callback that is triggered every time a key is pressed.

Key Binds

Variable	Type	Default	Possible Values	Description
keyCode	Number / String	null	KeyCode as integer or a mapped string	Key that should trigger the event. If null, any key will trigger event.
modifiers	Array	[]	['ctrlKey', 'shiftKey', 'altKey', 'metaKey']	Keys that needs to be pressed down before the actual key (key Code), e.g. Ctrl+A.
preventDefault	Boolean	false	true,false	Prevent the default action of the event
success	Function	null		Callback that is triggered when the correct key is pressed.

The return payload of the callbacks is like so:

{
  event: Object, // the official event object
  expectedEvent: Object, // your defined props.
  message: String // A declarative message on error/success.
}