Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 87 ยท Template Syntax

Handling Events

Listen to DOM events in Vue 3 with v-on and the @ shorthand. Compare inline and method handlers, use $event, event modifiers like prevent and stop, and key modifiers.

So far your templates have only displayed data. To react to the user you need to listen for events: clicks, key presses, form submissions, mouse movement. In Vue you do that with the v-on directive, written @ for short, which attaches a DOM event listener to an element and runs your code when the event fires.

This lesson covers the two kinds of handler, how to reach the event object, the modifiers that replace common event.preventDefault() boilerplate, and key modifiers for keyboard shortcuts.

v-on and the @ shorthand

v-on:click="..." and @click="..." mean exactly the same. The part after @ is the event name, and the value is either an inline statement or a method name. The shorthand is what nearly everyone writes:

Inline handlers

An inline handler is a small JavaScript statement written in the template. In the template, refs are unwrapped, so you write count++, not count.value++. Inline handlers are perfect for one-liners such as incrementing or toggling. When the logic grows, move it out.

Method handlers

If the value of @click is the name of a function (or a path like actions.save), Vue treats it as a method handler and calls it with the native event as its first argument:

A method handler that reads the event

Pressing the button prints type: click, tag: BUTTON, class: demo. Note that Vue detects a method handler from the shape of the expression: describe or obj.describe is a method, while describe() or count++ is an inline statement.

Calling methods with arguments, and $event

Inside an inline handler you can call a method with your own arguments. That is how you tell which item a click belongs to, for example in a v-for loop. If you also need the native event there, pass the special variable $event, or use an arrow function:

Arguments and $event

@click="inspect(item.name, $event)" passes the name you chose plus the real MouseEvent. The arrow-function form @click="(e) => inspect(item.name, e)" is equivalent.

sequenceDiagram
  participant U as User
  participant D as DOM element
  participant V as Vue listener
  participant H as Your handler
  participant S as Reactive state
  U->>D: click
  D->>V: native event
  V->>H: call with event, or with your arguments
  H->>S: change a ref
  S-->>D: Vue schedules a DOM update

An event listener is the bridge between a user action and a change to reactive state.

Event modifiers

Handlers often start with event.preventDefault() or event.stopPropagation(). These are DOM details, not business logic. Vue lets you declare them with modifiers appended to the event name with a dot:

Modifier Effect
.prevent Calls event.preventDefault()
.stop Calls event.stopPropagation()
.self Runs only when the event's target is the element itself, not a child
.once Runs at most one time
.capture Listens in the capture phase
.passive Registers a passive listener (useful for scroll and touch)
prevent, stop, self and once

Try each control and read the log. Clicking the first inner box logs two lines, because the click bubbles up to the outer box; the .stop box logs one. In the second outer box, clicking the padding logs a line, but clicking the child does nothing, because .self ignores events that started on a child.

Modifiers can be chained, and the order matters: @click.prevent.self prevents the default action of all clicks (including on children), while @click.self.prevent prevents only clicks on the element itself.

The most common use of .prevent is on a form submission, so the browser does not reload the page. You will use it in Building Forms.

Key modifiers

For keyboard events you often care about a particular key. Vue provides modifiers named after the key, using the kebab-case form of the KeyboardEvent.key value:

HTML
<input @keyup.enter="submit">
<input @keyup.page-down="next">

Aliases exist for the common keys: .enter, .tab, .delete (both Delete and Backspace), .esc, .space, .up, .down, .left and .right.

System modifier keys let you require a held key: .ctrl, .alt, .shift and .meta (Cmd on Mac, the Windows key on Windows). .exact requires exactly that combination and no others:

Key modifiers

The two inputs share the draft ref (see Two-Way Binding with v-model for how that works). Typing and pressing Enter in the first adds a note, and the typeof check tells a real event object from the string passed by the shortcut handler. Mouse buttons have modifiers too: .left, .right and .middle.

Mouse button and system key modifiers (reference)

Here is the complete family of modifiers in one place, with the details that the earlier tables skip.

Mouse button modifiers restrict a mouse handler to one button:

Modifier Responds to Notes
.left Primary button (usually left) Ignores other buttons
.right Secondary button @click.right is compiled to the contextmenu event, so it also fires for the keyboard menu key and long-press on touch
.middle Middle button or wheel click @click.middle is compiled to mouseup and checks event.button === 1

System modifier keys require a key to be held while the event happens. They work on keyboard and mouse events:

Modifier Key
.ctrl Control
.shift Shift
.alt Alt (Option on Mac)
.meta Cmd on Mac, the Windows key on Windows

With keyboard events there is a trap. @keyup.ctrl does not mean "the Ctrl key was released"; it fires when another key is released while Ctrl is held, and releasing Ctrl alone does not trigger it, because Ctrl is no longer down. To react to one specific combination, add a key modifier: @keyup.ctrl.s.

.exact makes the combination strict. @click.ctrl fires for Ctrl+click and also for Ctrl+Shift+click. @click.ctrl.exact fires only for Ctrl+click, and plain @click.exact fires only when no system key is held. This is how you give a link or a row different behaviour for a plain click, Shift+click (range select) and Ctrl+click (add to selection).

Two more modifiers to remember: .capture (listen while the event travels down to the target, so an outer element sees it first) and .passive. .passive promises the browser that your handler will not call preventDefault(), which lets scrolling stay smooth on touch and wheel events (@scroll.passive, @wheel.passive). Never combine .passive with .prevent; Vue warns, because the two promises contradict each other.

Mouse buttons, system keys and .exact

Try a plain click: two lines appear, because mousedown.left fires on press and the exact plain click fires on release. Ctrl+click triggers the Ctrl-only handler and not the plain one, because .exact on the plain handler means "no system key at all". Ctrl+Shift+click reaches only the handler that lists both keys. The .right.prevent pair suppresses the browser's context menu on this box only. (Some operating systems treat Ctrl+click as a right click, so test the Ctrl cases with a mouse on your platform.)

Use these sparingly. Hidden mouse and keyboard shortcuts are invisible to many users, so add a visible button or menu item for every important action and treat the modifiers as accelerators (accessibility).

Inline or method?

Use an inline handler for something that fits comfortably in a few characters: open = !open. Use a method when you need several statements, early returns or you want to reuse and test the logic. A method name in the template also documents what happens, which reads better than a block of statements.

Handlers run synchronously and can change state freely. Vue batches the resulting DOM updates, so several state changes in one handler produce a single re-render.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which two attributes are exactly equivalent?

    @ is the shorthand for v-on:. The colon alone is the shorthand for v-bind.
  2. 2. In @click="save($event, id)", what is $event?

    $event is the original DOM event, which you can pass along together with your own arguments.
  3. 3. Which modifier makes a handler run only when the element itself, not a child, was clicked?

    .self checks that event.target is the element that has the listener.
  4. 4. What does @keyup.ctrl.enter require?

    System modifiers such as .ctrl must be held while the key event fires.
  5. 5. What is the reason to use .prevent on a form's submit event?

    .prevent calls preventDefault(), which cancels the browser's default form submission.

Summary

  • @event="..." (short for v-on:event) attaches a listener; the value is an inline statement or a method name.
  • A method handler receives the native event; an inline handler can pass its own arguments plus $event.
  • Modifiers .prevent, .stop, .self, .once, .capture and .passive replace common DOM boilerplate, and their order matters when chained.
  • Key modifiers (.enter, .esc, .page-down...) filter keyboard events, and .ctrl, .alt, .shift, .meta and .exact handle combinations.
  • Keep inline handlers short and move longer logic into methods.

Next, learn how Vue keeps track of the data these handlers change in Reactive State with ref.