Event Handling

We can use the directive, which we typically shorten to the @ symbol, to listen to DOM events and run some JavaScript when they’re triggered. The usage would be v-on:click="methodName" or with the shortcut, @click="methodName"

For example:

Vue.createApp({
  data() {
    return {
      counter: 1
    }
  }
}).mount('#basic-event')

Result:

See the Pen Event handling: basic by Vue () on CodePen.

Method Event Handlers

The logic for many event handlers will be more complex though, so keeping your JavaScript in the value of the v-on attribute isn’t feasible. That’s why v-on can also accept the name of a method you’d like to call.

For example:

<div id="event-with-method">
  <!-- `greet` is the name of a method defined below -->
  <button @click="greet">Greet</button>
</div>

Vue.createApp({
  data() {
    return {
      name: 'Vue.js'
    }
  },
  methods: {
    greet(event) {
      // `this` inside methods points to the Vue instance
      alert('Hello ' + this.name + '!')
      // `event` is the native DOM event
      if (event) {
        alert(event.target.tagName)
      }
    }
  }
}).mount('#event-with-method')

Result:

See the Pen Event handling: with a method by Vue () on CodePen.

Instead of binding directly to a method name, we can also use methods in an inline JavaScript statement:

  <button @click="say('hi')">Say hi</button>
  <button @click="say('what')">Say what</button>
</div>

Result:

See the Pen by Vue (@Vue) on .

<button @click="warn('Form cannot be submitted yet.', $event)">
  Submit
</button>

// ...
methods: {
  warn(message, event) {
    if (event) {
      event.preventDefault()
    }
    alert(message)
  }
}

Event Modifiers

It is a very common need to call event.preventDefault() or event.stopPropagation() inside event handlers. Although we can do this easily inside methods, it would be better if the methods can be purely about data logic rather than having to deal with DOM event details.

To address this problem, Vue provides event modifiers for v-on. Recall that modifiers are directive postfixes denoted by a dot.

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

<!-- the click event's propagation will be stopped -->
<a @click.stop="doThis"></a>
<!-- the submit event will no longer reload the page -->
<form @submit.prevent="onSubmit"></form>
<!-- modifiers can be chained -->
<a @click.stop.prevent="doThat"></a>
<!-- just the modifier -->
<form @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 @click.capture="doThis">...</div>
<!-- i.e. not from a child element -->
<div @click.self="doThat">...</div>

TIP

Order matters when using modifiers because the relevant code is generated in the same order. Therefore using @click.prevent.self will prevent all clicks while @click.self.prevent will only prevent clicks on the element itself.

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

Unlike the other modifiers, which are exclusive to native DOM events, the .once modifier can also be used on . If you haven’t read about components yet, don’t worry about this for now.

Vue also offers the .passive modifier, corresponding to addEventListener‘s passive option.

The .passive modifier is especially useful for improving performance on mobile devices.

TIP

Don’t use .passive and together, because .prevent will be ignored and your browser will probably show you a warning. Remember, .passive communicates to the browser that you don’t want to prevent the event’s default behavior.

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

<!-- only call `vm.submit()` when the `key` is `Enter` -->
<input @keyup.enter="submit" />

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

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

Vue provides aliases for the most commonly used keys:

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

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 (⊞). On Sun Microsystems keyboards, meta is marked as a solid diamond (◆). On certain keyboards, specifically MIT and Lisp machine keyboards and successors, such as the Knight keyboard, space-cadet keyboard, meta is labeled “META”. On Symbolics keyboards, meta is labeled “META” or “Meta”.

For example:

<!-- Alt + Enter -->
<input @keyup.alt.enter="clear" />
<!-- Ctrl + Click -->
<div @click.ctrl="doSomething">Do something</div>

TIP

Note that modifier keys are different from regular keys and when used with keyup events, they have to be pressed when the event is emitted. In other words, 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

The .exact modifier allows control of the exact combination of system modifiers needed to trigger an event.

<!-- 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>

• .left
• .right
• .middle

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

You might be concerned that this whole event listening approach violates the good old rules about “separation of concerns”. Rest assured - since all Vue handler functions and expressions are strictly bound to the ViewModel that’s handling the current view, it won’t cause any maintenance difficulty. In fact, there are several benefits in using or @:

1. It’s easier to locate the handler function implementations within your JS code by skimming the HTML template.