Modifiers

The v-on directive also accepts modifiers to specify further which events are expected or limit an event's effects.

Event Modifiers

It is a very common need to call event.preventDefault() or event.stopPropagation() inside event handlers. To simplify this process of using such methods, Vue provides event modifiers for v-on. Modifiers are directive postfixes denoted by a dot.

The following is a list of the available event modifiers.

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

The .prevent modifier

The .prevent modifier will prevent an event from taking its default action. This means that forms will not cause a page refresh on submit, and links will not go to their destination.

In the example below, the .prevent modifier is used to divert a link.

const app = Vue.createApp({
  methods: {
    divert: function (event) {
      alert(event.target.href)
    }
  }
})

const vm = app.mount('#app')

<div id="app">
  <a href="http://google.ca" @click.prevent="divert">Diverted Link</a>
</div>

The .self modifier

The .self modifier will lock an event from being trigger by any children of the element with the event listener.

In the example below, the first set of boxes will cause an alert if any box was clicked. But the second, which uses the .self modifier, will only cause an alert if the white box (parent) is clicked.

const app = Vue.createApp({
  methods: {
    alert: function () {
      alert('Clicked!')
    }
  }
})

const vm = app.mount('#app')

<div id="app">
  <!-- clicking on any box will cause an alert -->
  <div class="box white" @click="alert">
    <h4 class="text-center">no .self</h4>
    <div class="box red"></div>
    <div class="box blue"></div>
  </div>
  
  <!-- Clicking only on the white box will cause an alert -->
  <div class="box white" @click.self="alert">
    <h4 class="text-center">.self</h4>
    <div class="box red"></div>
    <div class="box blue"></div>
  </div>
</div>

The .once modifier

The .once modifier will prevent an event from being activated more than once.

In the example below, the click event will only be triggered once.

const app = Vue.createApp({
  data: function () {
    return { counter: 0 }
  }
})

const vm = app.mount('#app')

<div id="app">
  <button class="btn btn-secondary" v-on:click.once="counter++">Button clicked {{ counter }} times</button>
</div>

Key Modifiers

When listening for keyboard events, we often need to check for specific keys. Vue allows adding key modifiers for v-on when listening for key events.

In the example below, the text in the input box will be alerted when the Enter key is pressed.

const app = Vue.createApp({
  methods: {
    submit: function (event) {
      alert(event.target.value)
    }
  }
})

const vm = app.mount('#app')

<div id="app">
  <!-- only call submit when the `key` is `Enter` -->
  <input class="form-control" @keyup.enter="submit">
</div>

You can directly use any valid key names exposed via KeyboardEvent.key as modifiers by converting them to kebab-case.

The following table shows a few of the modifiers and their key equivalents.

KeyboardEvent.key	Vue modifier
ArrowDown	.arrow-down
ArrowLeft	.arrow-left
ArrowRight	.arrow-right
ArrowUp	.arrow-up
PageDown	.page-down
PageUp	.page-up

System Modifier Keys

You can use the following modifiers to trigger mouse or keyboard event listeners only when the corresponding modifier key is pressed:

• .ctrl
• .alt
• .shift
• .meta

NOTE

On Macintosh keyboards, meta is the command key (⌘). On Windows keyboards, meta is the Windows key (⊞).

In the following example, using the ctrl + s key combination will cause an alert.

const app = Vue.createApp({
  methods: {
    save: function () {
      alert('Saved!')
    }
  }
})

const vm = app.mount('#app')

<div id="app">
  <!-- ctrl + s -->
  <input class="form-control" @keyup.ctrl.s="save">
</div>

Mouse Button Modifiers

These modifiers restrict the handler to events triggered by a specific mouse button.

• .left
• .right
• .middle