Modifier Basics

Modifiers are specialized symbols used to constrain declarations of types and their members in programming. In Vue, modifiers abstract away common low-level DOM event and data binding processing logic, allowing developers to focus on core business implementation instead of repetitive edge case handling.

Vue modifiers are grouped into 5 core categories:

• Form modifiers
• Event modifiers
• Mouse button modifiers
• Keyboard modifiers
• v-bind modifiers

---

Form Modifiers

Form modifiers are used with v-model on form input elements to adjust data synchronization behavior:

lazy

Delays v-model synchronization until the change event fires (usually when the input loses focus), rather than syncing on every input event:

<input type="text" v-model.lazy="userInput" />
<p>Synced value: {{ userInput }}</p>

trim

Automatically removes leading and trailing whitespace from user input, while preserving spaces between characters:

<input type="text" v-model.trim="searchKeyword" />

number

Automatically parses user input into a numeric value. If the input cannot be converted via parseFloat, the original raw string is returned:

<input v-model.number="userAge" type="number" />

---

Event Modifiers

Event modifiers adjust event propagation and default behavior handling:

stop

Prevents event bubbling up the DOM tree, equivalent to calling event.stopPropagation():

<div @click="triggerAlert(2)">
  <button @click.stop="triggerAlert(1)">Click Test</button>
</div>
<!-- Only 1 will be logged when clicking the button -->

prevent

Blocks the browser's default event behavior, equivalent to calling event.preventDefault():

<form @submit.prevent="handleFormSubmit"></form>

self

Only triggers the event handler if event.target is the bound element itself, ignoring bubbled events from child elements:

<div @click.self="processDirectClick">...</div>

Modifier order directly impacts implementation logic. @click.prevent.self blocks all click events on the element and its children, while @click.self.prevent only blocks default behavior for clicks directly on the element.

once

Binds an event handler that only executes a single time, and is automatically unbound after the first trigger:

<button @click.once="triggerAlert(1)">One-time Action</button>

capture

Enables event capture mode, where events are processed from the outermost bound elemant inward, instead of the default bubbling order:

<div @click.capture="logClick(1)">
  Outer Layer
  <div @click.capture="logClick(2)">
    Middle Layer
    <div @click="logClick(3)">
      Inner Layer
      <div @click="logClick(4)">Core Element</div>
    </div>
  </div>
</div>
<!-- Output order when clicking core element: 1 2 4 3 -->

passive

Optimizes scroll event performance, especially on mobile devices, by telling the browser to execute the default scroll behavior immediately without waiting for the event handler to complete:

<div @scroll.passive="handleScroll">Long scrollable content</div>

Do not combine .passive with .prevent - the prevent call will be ignored, and browsers may throw a warning. This modifier explicitly signals that you do not intend to block default event behavior.

native

Listens for native DOM events on the root element of a custom component. Without this modifier, v-on on custom components only detects emitted custom events:

<custom-card @click.native="handleCardSelect"></custom-card>

The .native modifier will not work when applied to native HTML tags.

---

Mouse Button Modifiers

Restrict click event handlers to trigger only when specific mouse buttons are pressed:

• .left: Left mouse button
• .right: Right mouse button
• .middle: Mouse wheel / middle button

<button @click.left="logAction('left')">Left Click Only</button>
<button @click.right="logAction('right')">Right Click Only</button>
<button @click.middle="logAction('middle')">Middle Click Only</button>

---

Keyboard Modifiers

Used with keyup and keydown events to trigger handlers only when specific keys are pressed. Vue provides pre-defined aliases for common keys to avoid hardcoding keyCodes:

• Common keys: enter, tab, delete, space, esc, up, down, left, right
• System modifier keys: ctrl, alt, shift, meta

<!-- Triggers form submit only when enter is pressed -->
<input type="text" @keyup.enter="submitForm" />

You can also define custom global key aliases:

Vue.config.keyCodes.f2 = 113

---

v-bind Modifiers

Adjust attribute binding behavior for v-bind directives:

async

Enables simplified two-way binding for component props:

<!-- Parent component -->
<child-comp :userNote.sync="activeNote"></child-comp>

<!-- Child component emit call -->
this.$emit('update:userNote', updatedNoteContent)

This is shorthand for the full two-way binding implementation:

<!-- Parent component full implementation -->
<child-comp :userNote="activeNote" @update:userNote="val => activeNote = val"></child-comp>

Key notes for .sync usage:

• The emitted event name must follow the update:[propName] format, matching the declared prop name exactly
• .sync cannot be used with dynamic expressions
• .sync does not support binding to literal objects, e.g. v-bind.sync="{ title: doc.title }" will not function correctly

prop

Binds values as DOM element properties instead of HTML attributes, which prevents sensitive data from being exposed in the DOM structure and avoids attribute pollution:

<input id="uid" title="sample input" value="1" :sortIndex.prop="currentSortIndex" />

camel

Converts kebab-case attribute names to camelCase when binding, which is required for SVG attributes like viewBox:

<svg :view-box.camel="svgViewBoxConfig"></svg>

---

Common Application Scenarios

• .stop: Prevent event bubbling across nested interactive elements
• .native: Attach native event listeners to custom component root nodes
• .once: Restrict one-time actions such as initial form submission or payment triggers
• .self: Avoid unintended handler triggers from bubbled events on child elements
• .prevent: Block default browser behavior such as form submit page reloads or link navigation
• .capture: Prioritize event handling on parent elements before processing child events
• Key modifiers: Implement keyboard shortcuts or form submission via specific keys like enter
• Mouse button modifiers: Restrict context menu actions or special interactions to specific mouse buttons