lupas / vue-keypress

Global keypress event handler component for Vue.js applications.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Downloads Version License

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"
]

About

Global keypress event handler component for Vue.js applications.


Languages

Language:Vue 88.4%Language:JavaScript 6.2%Language:HTML 5.5%