v-on

The v-on directive is used to listen to DOM events and execute JavaScript when those events occur. Its basic syntax is v-on:event="handler". Here, the value of handler can be one of the following:

• Inline handlers: Inline JavaScript expressions that run when the event is triggered (similar to the native onclick attribute).
• Method handlers: The name (or path) of a method defined on the component.

<!-- Inline handler -->
<button v-on:click="count++">Add 1</button>

<!-- Method Handler (doSomething is a method defined on the component) -->
<a v-on:click="doSomething"> ... </a>

When using a method handler, Vue automatically passes the native DOM Event object as the first argument. You can access it via the method parameter (commonly named event) and inspect properties such as event.target.

Shorthand

Vue provides a shorthand syntax for v-on directive as well. You can replace v-on: with @:

<a @click="doSomething"> ... </a>

This shorthand works for all event listeners supported by v-on.

Accessing Event Argument in Inline Handlers

Sometimes you may also need to access the original DOM event in an inline handler. You can pass it into a method using the special $event variable, or use an inline arrow function.

<!-- Using $event -->
<button @click="handleClick($event)">Click me</button>

<!-- Using an inline arrow function -->
<button @click="(event) => handleClick(event)">Click me</button>

This approach is useful when you need to pass both custom arguments and the original event:

<button @click="handleClick('hello', $event)">Click me</button>

Event Modifiers

It is a very common to call event.preventDefault() or event.stopPropagation() inside event handlers. Although this can be done inside methods, it is often better for methods to focus purely on application logic rather than DOM-specific concerns.

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

Event Modifiers let you control event flow, an event’s default behavior, and how event listeners are registered.

TIP

To fully understand event modifiers, it helps to have a good understanding of Event Propagation and addEventListener in JavaScript. If you want a quick overview, you may choose to watch this video by Web Dev Simplified on YouTube.

Common Event Modifiers

Modifier	Description
.stop	Calls event.stopPropagation()
.prevent	Calls event.preventDefault()
.self	Triggers the handler only if the event originated from this element
.capture	Adds the event listener in capture mode. Attaches the event with { capture: true }
.once	Triggers the handler at most once. Attaches the event with { once: true }
.passive	Attaches the event with { passive: true }

As you can see, the .capture, .once and .passive modifiers mirror the options of the native addEventListener method.

Examples

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

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

NOTE

Order matters when using modifiers because the relevant code is generated in the same order. For example, using @click.prevent.self prevents the click's default action on the element and its children, while @click.self.prevent only prevents the click's default action when the event originates from the element itself.

Key Modifiers

Key modifiers are used to make event handlers run only for specific keyboard keys.

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

Key Aliases

Vue provides aliases for the most commonly used keys:

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

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

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

System Modifier Keys

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

• .ctrl
• .alt
• .shift
• .meta (On macOS this is the Command key ⌘. On Windows and Linux, the Windows key ⊞)

<!-- Alt + Enter -->
<input @keyup.alt.enter="clear" />

<!-- Ctrl + Click -->
<div @click.ctrl="doSomething">Do something</div>

.exact Modifier

The .exact modifier allows you to control the exact combination of system modifiers required 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>

Mouse Button Modifiers

Mouse button modifiers restrict handlers to events triggered by a specific mouse button:

• .left -> main button
• .right -> secondary button
• .middle -> auxiliary button

These represent logical buttons, not physical ones, so behavior may differ across devices such as mouse, trackpad and touch-based input.

<!-- left click only -->
<button @click.left="onLeftClick">Left</button>

<!-- right click only -->
<button @click.right="openContextMenu">Right</button>

<!-- middle click only -->
<button @click.middle="onMiddleClick">Middle</button>