iFgR / Vue Shortkey

Vue-ShortKey - plugin for VueJS 2.x accepts shortcuts globaly and in a single listener.

Install

npm install vue-shortkey --save

Usage

Vue.use(require('vue-shortkey'))

Add the shortkey directive to the elements that accept the shortcut. The shortkey must have explicitly which keys will be used.

Running functions

_{The code below ensures that the key combination ctrl + alt + o will perform the 'theAction' method.}

<button v-shortkey="['ctrl', 'alt', 'o']" @shortkey="theAction()">Open</button>

The function in the modifier @shortkey will be called repeatedly while the key is pressed. To call the function only once, use the once modifier

<button v-shortkey.once="['ctrl', 'alt', 'o']" @shortkey="theAction()">Open</button>

Multi keys

<button v-shortkey="{up: ['arrowup'], down: ['arrowdown']}" @shortkey="theAction">Joystick</button>

... and your method will be called with the key in the parameter

methods: {
  theAction (event) {
    switch (event.srcKey) {
      case 'up':
        ...
        break
      case 'down':
        ...
        break

Setting the focus

You can point the focus with the shortcut easily. _{The code below reserves the ALT + I key to set the focus to the input element.}

<input type="text" v-shortkey.focus="['alt', 'i']" v-model="name" />

Push button

Sometimes you may need a shortcut works as a push button. It calls the function one time when you click the button. When you release the shortcut, it calls the same function again like a toggle. In these cases, insert the "push" modifier.

The example below shows how to do this

<tooltip v-shortkey.push="['f3']" @shortkey="toggleToolTip"></tooltip>

Using on a component

Use the modifier native to catch the event.

 <my-component v-shortkey="['ctrl', 'alt', 'o']" @shortkey.native="theAction()"></my-component>

Multiple listeners

Use the modifier propagate to let the event propagate to other listeners

 <my-component v-shortkey="['ctrl', 'alt', 'o']" @shortkey.propagate="anAction()"></my-component>
 <my-component v-shortkey="['ctrl', 'alt', 'o']" @shortkey.propagate="aDifferentAction()"></my-component>

Key list

You can make any combination of keys as well as reserve a single key.

<input type="text" v-shortkey="['q']" @shortkey="foo()"/>
<button v-shortkey="['ctrl', 'p']" @shortkey="bar()"></button>
<button v-shortkey="['f1']" @shortkey="help()"></button>
<textarea v-shortkey="['ctrl', 'v']" @shortkey="dontPaste()"></textarea>

Avoided fields

You can avoid shortcuts within fields if you really need it. This can be done in two ways:

• Preventing a given element from executing the shortcut by adding the v-shortkey.avoid tag in the body of the element

<textarea v-shortkey.avoid></textaea>

• Generalizing type of element that will not perform shortcut. To do this, insert a list of elements in the global method.

Vue.use('vue-shortkey', { prevent: ['input', 'textarea'] })

• Or even by class

Vue.use('vue-shortkey', { prevent: ['.my-class-name', 'textarea.class-of-textarea'] })

Other uses

With the dynamism offered by Vue, you can easily create shortcuts dynamically

<li v-for="(ctx, item) in items">
  <a
    href="https://vuejs.org"
    target="_blank"
    v-shortkey="['f' + (item + 1)]"
    @shortkey="testa(item)"
    @click="testa()">
      F {{ item }}
  </a>
</li>

Integrating with Nuxt

Create /plugins/vue-shortkey.js and add the following to it

import Vue from 'vue'
const ShortKey = require('vue-shortkey')

// add any custom shortkey config settings here
Vue.use(ShortKey, { prevent: ['input', 'textarea'] })

export default ShortKey

Load the plugin in nuxt.config.js:

plugins: [ { src: '@/plugins/vue-shortkey.js', mode: 'client' }]

The mode: 'client' is necessary to prevent Nuxt from loading the plugin during server-side rendering (SSR).

Unit Test

npm test