README.md

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.

‼️ Vue 3 Support

This repository is for vue-keypress and is not maintained any longer.

If you are using Vue 3, visit the repository lupas/vue3-keypress

How to install?

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

How to use in your project?

Import the component in any .vue file like so:

...
components: {
  Keypress: () => import('vue-keypress')
}
...

Simple Usage

<template>
  <Keypress key-event="keyup" :key-code="13" @success="someMethod" />
</template>

<script>
export default {
  components: {
    Keypress: () => import('vue-keypress')
  },
  methods: {
    someMethod(response) {
      // Do something
    }
  }
}
</script>

Props

Prop	Type	Default	Possible Values	Description
keyEvent	String	'keyup'	keydown, keypress, keyup
keyCode	Number	null	see here	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
multipleKeys	Array	[]	See example in 'Multiple Keys'	Allows you to define multiple keyCode/modifier combinations per keyEvent.

If you use multipleKeys, all the other props (except keyEvent) become redundant.

Events

Event	Description
@success	Get's emitted when the defined key/modifiers were pressed.
@wrong	Get's emitted when the wrong key(s) or modifier(s) was/were pressed.
@any	Get's emitted with any keypress in any case.

All of them return a payload like so:

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

Multiple Keys

The multiple-keys prop allows for defining multiple keys (or key-modifier combinations) per key-event that can be pressed for success.

All the other props except key-event become redundant.

<template>
  <Keypress key-event="keyup" :multiple-keys="multiple" @success="someMethod" />
</template>

<script>
export default {
  components: {
    Keypress: () => import('vue-keypress')
  },
  data: () => ({
    multiple: [
        {
          keyCode: 65, // A
          modifiers: ['shiftKey'],
          preventDefault: true,
        },
        {
          keyCode: 83, // S
          modifiers: ['shiftKey'],
          preventDefault: false,
        },
      ],
  }),
  methods: {
    someMethod(response) {
      // Do something
    }
  }
}
</script>

Multiple Key Events

Multiple key events means that multiple event handlers for each evennt need to be registered. To do this, simply put your props in an array and register the component multiple times, like so:

<template>
    <Keypress
      v-for="keypressEvent in keypressEvents"
      :key="keypressEvent.id"
      :key-event="keypressEvent.keyEvent"
      :multiple-keys="keypressEvent.multipleKeys"
      @success="someMethod"
    />
</template>

<script>
export default {
  components: {
    Keypress: () => import('vue-keypress'),
  },
  data() {
    return {
      keypressEvents: [
        {
          keyEvent: 'keydown',
          multipleKeys: [
            {
              keyCode: 65, // A
              modifiers: ['shiftKey'],
              preventDefault: true,
            },
            {
              keyCode: 83, // S
              modifiers: ['shiftKey'],
              preventDefault: false,
            },
          ],
        },
        {
          keyEvent: 'keyup',
          multipleKeys: [
            {
              keyCode: 65, // A
              modifiers: ['shiftKey'],
              preventDefault: true,
            },
            {
              keyCode: 83, // S
              modifiers: ['shiftKey'],
              preventDefault: false,
            },
          ],
        },
      ],
    }
  },
  methods: {
    someMethod(response) {
      // Do something
    }
  },
}
</script>

Typescript Support

Add the following to your tsconfig.json:

"types": [
  "vue-keypress"
]