Vue v-on Directive
Example
Using the v-on directive to change the background color of a <div> element when when a button is clicked.
<template>
<h1>v-on Example</h1>
<div v-bind:class="{ yelClass: bgColor }">
<p>Click the button to change background color of this DIV box.</p>
<button v-on:click="bgColor = !bgColor">Click</button>
<p>bgColor property: "{{ bgColor }}"</p>
</div>
</template>
See more examples below.
Definition and Usage
The v-on directive is placed on an element to attach an event listener.
To attach an event listener with v-on we need to provide the event type, and any modifier, and a method or expression that should run when that event occurs.
If v-on is placed on a regular HTML tag, the event types we can define to listen to are the regular events like input, click or mouseover.
If v-on is placed on a custom component, the event types we can define to listen to are the custom events that are emitted from that component.
The shorthand for v-on: is @.
Modifiers
| Modifier | Details | |
|---|---|---|
.capture |
A bubbling event is captured first where the .capture modifier is set. |
Run Example » |
.once |
The event can only fire one time after loading the page. | Run Example » |
.passive |
Marks the event handler as passive by setting passive: true on the DOM element. This means that the browser does not have to wait to see if event.preventDefault() is called, and for events that happen very often, like scroll, setting the event handler as passive can enhance performance. |
Run Example » |
.prevent |
The event is prevented from firing. Can be used to for example prevent the default form submit event. It is not possible to prevent all events. | Run Example » |
.stop |
A bubbling event is stopped from propagating any further. The event.stopPropagation() is called. |
Run Example » |
.self |
By default, events propagates upwards to parent elements and one event can therefore trigger many event listeners. The .self modifier only lets events from its own element trigger the event listener. |
Run Example » |
.{keyAlias} |
Limits the event handler to only react to certain event keys, for example v-on:click.right or v-on:keyup.s. We can even demand that more than one key need to happen simultaneously for the handler to react, like this: v-on:click.left.shift. |
Run Example » |
.left |
Left button mouse click. | |
.right |
Right button mouse click. | |
.middle |
Middle button mouse click. |
More Examples
Example 1
Using the .capture modifier to capture the click event in the parent element first.
<template>
<h1>v-on Example</h1>
<p>When the '.capture' modifier is used on the parent DIV element, the event is captured first in the parent element when the child element is clicked.</p>
<p>If the '.capture' modifier is removed from this code, the child element will capture the click event first. This is the default behavior, that the event bubbles up, first in child element, then to the parent.</p>
<div v-on:click.capture="this.msg.push('parent')" id="parent">
<p>This is the parent element.</p>
<div v-on:click="this.msg.push('child')">
<p>This is the child element. CLICK HERE!</p>
</div>
</div>
<p>The order of when and where the event is captured.</p>
<ol>
<li v-for="x in msg">{{ x }}</li>
</ol>
</template>
<script>
export default {
data() {
return {
msg: []
};
}
}
</script>
<style scoped>
div {
margin: 10px;
padding: 10px;
border: dashed black 1px;
}
#parent {
width: 250px;
background-color: lightpink;
}
#parent > div {
cursor: pointer;
background-color: lightgreen;
}
</style>
Example 2
Using the .stop modifier to prevent the event from propagating any further.
<template>
<h1>v-on Example</h1>
<p>The '.stop' modifier stops the click event from propagating any further.</p>
<p>If the '.stop' modifier is removed from this code, the parent element will also capture the click event on the child element.</p>
<div v-on:click="this.msg.push('parent')" id="parent">
<p>This is the parent element.</p>
<div v-on:click.stop="this.msg.push('child')">
<p>This is the child element. CLICK HERE!</p>
</div>
</div>
<p>The order of when and where the event is captured.</p>
<ol>
<li v-for="x in msg">{{ x }}</li>
</ol>
</template>
<script>
export default {
data() {
return {
msg: []
};
}
}
</script>
<style scoped>
div {
margin: 10px;
padding: 10px;
border: dashed black 1px;
}
#parent {
width: 250px;
background-color: lightpink;
}
#parent > div {
cursor: pointer;
background-color: lightgreen;
}
</style>
Example 3
Using the .passive modifier to enhance performance during scrolling.
<template>
<h1>v-on Example</h1>
<p>The '.passive' modifier sets the event handler as passive, and this can enhance performance.</p>
<div v-on:scroll.passive="this.scrollTimes++" id="parent">
<p>Scroll here.</p>
<p>Bladi-bladi-bladi</p>
<p>potato potato</p>
<p>Scroll-scroll-scroll</p>
<p>Scroll more...</p>
</div>
<p>Scroll happended {{ scrollTimes }} times.</p>
</template>
<script>
export default {
data() {
return {
scrollTimes: 0
};
}
}
</script>
<style scoped>
div {
margin: 10px;
padding: 10px;
border: dashed black 1px;
width: 200px;
height: 50px;
overflow: scroll;
background-color: lightcoral;
}
</style>
Example 4
Using the .once modifier to enhance performance during scrolling.
<template>
<h1>v-on Example</h1>
<p>The '.once' modifier prevents the event from happening more than once.</p>
<button v-on:click.once="clickTimes++">Click</button>
<p>Click event happened {{ clickTimes }} times.</p>
</template>
<script>
export default {
data() {
return {
clickTimes: 0
};
}
}
</script>
Example 5
Using the .self modifier so that the parent element only reacts to click events that happen to itself.
<template>
<h1>v-on Example</h1>
<p>The '.self' modifier is set on the parent element. </p>
<p>Click on the child element and see how the event propagates past the parent element because the parent click event only reacts to click on the element itself.</p>
<div v-on:click="addMsg('grandParent')" id="grandParent">
Grandparent element
<div v-on:click.self="addMsg('parent')">
Parent element.
<div v-on:click="addMsg('child')">
Child element. CLICK HERE!
</div>
</div>
</div>
<p>The order of when and where the event is captured.</p>
<ol>
<li v-for="x in msg">{{ x }}</li>
</ol>
</template>
<script>
export default {
data() {
return {
msg: []
};
},
methods: {
addMsg(txt) {
this.msg.push(txt);
}
}
}
</script>
<style scoped>
div {
margin: 10px;
padding: 10px;
border: dashed black 1px;
cursor: pointer;
}
#grandParent {
width: 250px;
background-color: lightpink;
}
#grandParent > div {
background-color: lightgreen;
}
#grandParent > div > div {
background-color: lightskyblue;
}
</style>
Example 6
Using the .prevent modifier to prevent the default drop down list from appearing when right mouse button click.
<template>
<h1>v-on Example</h1>
<p>The '.prevent' modifier is set to prevent the drop down menu to appear when the user does a right mouse button click.</p>
<div
v-on:click.right.prevent="changeColor"
v-bind:style="{ backgroundColor: 'hsl(' + bgColor + ',80%,80%)' }">
<p>Press right mouse button here.</p>
</div>
</template>
<script>
export default {
data() {
return {
bgColor: 0
}
},
methods: {
changeColor() {
this.bgColor += 50
}
}
}
</script>
<style scoped>
div {
margin: 10px;
padding: 10px;
border: dashed black 1px;
width: 200px;
}
</style>
Example 7
Using the .left.shift modifiers to change image when the user does a left mouse button click while holding down the shift key.
<template>
<h1>v-on Example</h1>
<p>Hold 'Shift' key and press left mouse button on the image:</p>
<img v-on:click.left.shift="changeImg" v-bind:src="imgUrl">
</template>
<script>
export default {
data() {
return {
imgFish: true,
imgUrl: 'img_fish.svg'
}
},
methods: {
changeImg() {
this.imgFish = !this.imgFish;
if (this.imgFish) {
this.imgUrl = 'img_fish.svg'
}
else {
this.imgUrl = 'img_tiger.svg'
}
}
}
}
</script>
<style scoped>
img {
width: 200px;
}
</style>
Related Pages
Vue Tutorial: Vue Events
Vue Tutorial: Vue v-on Directive
Vue Tutorial: Vue Methods
Vue Tutorial: Vue Event Modifiers
JavaScript Tutorial: JavaScript Events
