Event Handling Back

This chapter only aims to describe how to handle events with Vue.

1. DOM Events Listener

If we want to listen to DOM events and handle it, we can use v-on:<event-type> directive to do so:

<div id="app" v-on:click="handler"></div>

const vm = new Vue({
    el: '#app',
    methods: {
        handler: () => {/** event handler */},
    },
});

If you want to pass parameters through inline methods, you can also do this like the following snippet:

<div id="app" v-on:click="handler('param')"></div>

const vm = new Vue({
    el: '#app',
    methods: {
        handler: str => { console.log(str);/** => "param" */ },
    },
});

What if requiring the original event in the handler? Just pass it with $event variable:

<div id="app" v-on:click="handler('param', $event)"></div>

const vm = new Vue({
    el: '#app',
    methods: {
        handler: (str, event) => { console.log(event.target);/** => DOM Element */ },
    },
});

2. Modifiers

2.1 Event Modifiers

As it is very common to call event.preventDefault() or event.stopPropagation() inside event handlers, and Vue has provided developers a more simple way to let handlers focus more purely on data logic rather than event details, which is named with event modifiers:

.stop
.prevent
.capture
.self
.once
.passive

<!-- the click event's propagation will be stopped -->
<a v-on:click.stop="doThis"></a>

<!-- the submit event will no longer reload the page -->
<form v-on:submit.prevent="onSubmit"></form>

<!-- modifiers can be chained -->
<a v-on:click.stop.prevent="doThat"></a>

<!-- just the modifier -->
<form v-on:submit.prevent></form>

<!-- use capture mode when adding the event listener -->
<!-- i.e. an event targeting an inner element is handled here before being handled by that element -->
<div v-on:click.capture="doThis">...</div>

<!-- only trigger handler if event.target is the element itself -->
<!-- i.e. not from a child element -->
<div v-on:click.self="doThat">...</div>

Note: order matters because the relevant code is generated in the same order, which means that different orders will have different impact. v-on:click.prevent.self will prevent all clicks, while v-on:click.self.prevent will only prevent clicks on the element itself.

.once

Since [email protected], Vue has provided us another modifiers to make sure that event will be only handled at most once:

<!-- the click event will be triggered at most once -->
<a v-on:click.once="doThis"></a>

.passive

Since [email protected], Vue has provided us another modifiers, corresponding to addEventListener's passive option:

<!-- the scroll event's default behavior (scrolling) will happen -->
<!-- immediately, instead of waiting for `onScroll` to complete  -->
<!-- in case it contains `event.preventDefault()`                -->
<div v-on:scroll.passive="onScroll">...</div>

Note:

the .passive modifier is especially useful for improving performance on mobile devices.
do not use .passive and .prevent together, because .prevent will be ignored and warning info will be thrown by browsers.

2.2 Key Modifiers

When listening to keyboard events, like keyup, keydown, etc., we may need to check for common key codes like 13 for the enter key. Vue has also provided developers modifiers for handling simply:

<!-- only call `vm.submit()` when the `keyCode` is 13 -->
<input v-on:keyup.13="submit" />

At the same time, there are also aliases for that most commonly used keys:

.enter
.tab
.delete (captures both "Delete" and "Backspace" keys)
.esc
.space
.up
.down
.left
.right

<!-- same as above -->
<input v-on:keyup.enter="submit" />

Besides, custom key modifier aliases are also enabled via the global config.keyCodes object:

Vue.config.keyCode.f1 = 112; /** enable `v-on:keyup.f1` */

Since [email protected], Vue has supported for any valid key names exposed via KeyboardEvent.key as modifiers by converting them to kebab-case:

<input @keyup.page-down="onPageDown" />

Note: a few keys have inconsistent key code in IE9.

Some system modifier keys have also been supported since [email protected], which we can used with chained styles:

.ctrl
.alt
.shift
.meta (⌘ on Macintosh Keyboards, while ⊞ on Windows keyboards, and while ◆ on Sun Microsystems keyboards.)

<!-- Alt + C -->
<input @keyup.alt.67="clear" />

Note: keyup.ctrl will only trigger if you release a key while holding down ctrl. It won't trigger if you release the ctrl key alone. If you do want such behaviour, use the keyCode for ctrl instead: keyup.17.

To specify exactly key code, we can use .exact modifier since [email protected]:

<!-- this will fire even if Alt or Shift is also pressed -->
<button @click.ctrl="onClick">A</button>

<!-- this will only fire when Ctrl and no other keys are pressed -->
<button @click.ctrl.exact="onCtrlClick">A</button>

<!-- this will only fire when no system modifiers are pressed -->
<button @click.exact="onClick">A</button>

2.3 Mouse button Modifiers

This is new feature since [email protected]:

.left
.right
.middle

Event Handling