Event Propagation and Default Behavior Modifiers

.stop – Halting Event Bubbling

Event bubbling causes a triggered event to propagate upward through the DOM tree. The .stop modifier intercepts this propagation, functioning identically to invoking event.stopPropagation() within the handler.

<template>
  <section @click="handleContainerTap" class="wrapper">
    <button @click.stop="handleActionTap">Execute</button>
  </section>
</template>

<script setup>
const handleContainerTap = () => console.log('Wrapper interacted');
const handleActionTap = () => console.log('Button activated');
</script>

Clicking the button triggers handleActionTap but prevents the event from reaching the parent <section>, ensuring handleContainerTap remains silent.

.prevent – Suppressing Default Actions

Certain DOM elements trigger inherent browser behaviors, such as form submissions reloading the page or anchor tags navigating to a URL. The .prevent modifier calls event.preventDefault() automatically, allowing custom logic to run without interrupting the user flow.

<template>
  <form @submit.prevent="processPayload">
    <input v-model="searchQuery" placeholder="Enter query" />
    <button type="submit">Run Search</button>
  </form>
  <a href="/dashboard" @click.prevent="interceptNavigation">Dashboard</a>
</template>

<script setup>
import { ref } from 'vue';
const searchQuery = ref('');

const processPayload = () => console.log('Processing:', searchQuery.value);
const interceptNavigation = () => console.log('Navigation intercepted');
</script>

.once – Single-Execution Listaners

Attaching .once ensures the bound handler detaches itself immediately after the first invocation. This is optimal for initialization routines, one-time acknowledgments, or irreversible UI actions.

<template>
  <button @click.once="initializeModule">Initialize System</button>
  <p v-if="isInitialized">System ready.</p>
</template>

<script setup>
import { ref } from 'vue';
const isInitialized = ref(false);

const initializeModule = () => {
  isInitialized.value = true;
  console.log('Module initialized. Listener removed.');
};
</script>

.self – Target-Filtered Execution

The .self modifier restricts handler execution to cases where event.target strictly matches the element hosting the listener. Events bubbling up from child nodes are ignored.

<template>
  <div @click.self="closeBackdrop" class="modal-overlay">
    <div class="modal-content" @click="handleContentClick">
      Modal Body
    </div>
  </div>
</template>

<script setup>
const closeBackdrop = () => console.log('Backdrop clicked, closing modal');
const handleContentClick = () => console.log('Content clicked');
</script>

Clicking the inner .modal-content triggers its own handler but bypasses closeBackdrop. Only direct clicks on .modal-overlay execute the parent logic.

.capture – Capture Phase Binding

DOM events traverse in two phases: capture (top-down) and bubble (bottom-up). By default, Vue ataches listeners during the bubbling phase. Appending .capture registers the listener during the capture phase, causing outer elements to react before inner ones.

<template>
  <div @click.capture="logCapture" class="outer-panel">
    <div @click="logBubble" class="inner-panel">Target</div>
  </div>
</template>

<script setup>
const logCapture = () => console.log('1. Capture phase triggered');
const logBubble = () => console.log('2. Bubble phase triggered');
</script>

.native – Root Element Binding (Vue 2 Context)

In Vue 2, attaching event listeners directly to custom components binds to custom events emitted via $emit, not native DOM events. The .native modifier forces the listener onto the component's root DOM node. Note: Vue 3 automatically falls through non-prop attributes and listeners to the root element, rendering .native obsolete in modern implementations.

<!-- Vue 2 Implementation -->
<custom-wrapper @click.native="handleNativeClick">Content</custom-wrapper>

.passive – Performance Optimization for Scroll/Touch

Frequent events like scroll, touchmove, and wheel can cause main-thread blocking if the browser must wait to determine if preventDefault() will be called. The .passive modifier explicitly signals that the default behavior will never be canceled, allowing the browser to handle scrolling asynchronously without waiting for JavaScript execution.

<template>
  <div @scroll.passive="trackScrollPosition" class="scroll-container">
    <!-- Long content -->
  </div>
</template>

<script setup>
const trackScrollPosition = (e) => {
  console.log('Scroll Y:', e.target.scrollTop);
};
</script>

Modifier Order Matters: Chained modifiers execute sequentially. @click.prevent.self blocks all clicks before checking the target, while @click.self.prevent only blocks default actions for direct clicks on the element itself.

Form Input Modifiers

.lazy – Deferred Synchronization

By default, v-model syncs data on every input event. The .lazy modifier shifts synchronization to the change event, updating the bound variable only when the input loses focus or the user presses Enter.

<template>
  <textarea v-model.lazy="draftText" placeholder="Compose message..."></textarea>
  <p>Synced on blur: {{ draftText }}</p>
</template>

<script setup>
import { ref } from 'vue';
const draftText = ref('');
</script>

.number – Automatic Type Casting

HTML inputs always return string values. The .number modifier automatically parses the input using parseFloat(). If parsing fails, the original string is retained. This does not restrict keyboard input; it only transforms the bound data type.

<template>
  <input v-model.number="itemCount" type="text" placeholder="Quantity" />
  <p>Type: {{ typeof itemCount }} | Value: {{ itemCount }}</p>
</template>

<script setup>
import { ref } from 'vue';
const itemCount = ref(0);
</script>

.trim – Whitespace Sanitization

Automatically strips leading and trailing whitespace from user input before updating the bound variable. Internal spacing remains intact.

<template>
  <input v-model.trim="userHandle" placeholder="Username" />
  <p>Cleaned: [{{ userHandle }}]</p>
</template>

<script setup>
import { ref } from 'vue';
const userHandle = ref('');
</script>

Keyboard and Mouse Modifiers

Key Aliases and System Modifiers

Vue maps common key codes to readable aliases, eliminating the need to memorize numeric key codes. System modifiers allow combination shortcuts.

Common Aliases: .enter, .tab, .delete, .esc, .space, .up, .down, .left, .right
System Modifiers: .ctrl, .alt, .shift, .meta

<template>
  <input @keydown.enter="submitData" placeholder="Press Enter" />
  <input @keyup.ctrl.s="saveWork" placeholder="Ctrl+S shortcut" />
</template>

<script setup>
const submitData = () => console.log('Submitted');
const saveWork = () => console.log('Saved');
</script>

.exact – Strict Modifier Matching

System modifiers trigger even when additional keys are pressed. The .exact modifier enforces strict key combinations, ensuring the handler only fires when the specified keys are pressed and no others are active.

<template>
  <!-- Triggers with Ctrl, regardless of Shift/Alt state -->
  <button @click.ctrl="runLoose">Loose Ctrl</button>
  
  <!-- Triggers ONLY when Ctrl is pressed alone -->
  <button @click.ctrl.exact="runStrict">Strict Ctrl</button>
  
  <!-- Triggers ONLY when NO system keys are active -->
  <button @click.exact="runPlain">Plain Click</button>
</template>

Mouse Button Filters (.left, .right, .middle)

These modifiers filter pointer events based on the specific mouse button activated. They are typically paired with @click, @mousedown, or @contextmenu.

<template>
  <div 
    @click.left="handlePrimary" 
    @contextmenu.prevent.right="handleSecondary"
    @mousedown.middle="handleAuxiliary"
    class="interactive-zone"
  >
    Interaction Canvas
  </div>
</template>

<script setup>
const handlePrimary = () => console.log('Left click');
const handleSecondary = () => console.log('Right click');
const handleAuxiliary = () => console.log('Middle click');
</script>

Prop and Attribute Modifiers

.sync – Two-Way Prop Binding (Vue 2)

The .sync modifier provides a shorthand for two-way prop binding. It automatically listens for an update:propName event emitted by the child component and updates the parent's data accordingly. In Vue 3, this pattern is unified under multiple v-model arguments.

<!-- Parent Component -->
<template>
  <child-panel :is-visible.sync="showPanel" />
</template>

<script>
export default {
  data() { return { showPanel: false }; }
}
</script>

<!-- Child Component -->
<script>
export default {
  props: ['isVisible'],
  methods: {
    dismiss() {
      this.$emit('update:is-visible', false);
    }
  }
}
</script>

.prop – DOM Property Binding

HTML attributes and DOM properties are distinct. By default, v-bind sets attributes. The .prop modifier forces the binding to target the underlying DOM property directly, which is necessary for properties that do not reflect as attributes or when avoiding HTML pollution.

<template>
  <div :data-config.prop="rawSettings"></div>
</template>

<script setup>
import { ref } from 'vue';
const rawSettings = ref({ theme: 'dark', version: 2 });
</script>

.camel – Case Conversion for Attributes

HTML attributes are case-insensitive, which causes issues with case-sensitive SVG properties or custom DOM properties. The .camel modifier converts kebab-case binding names into camelCase during rendering.

<template>
  <svg :view-box.camel="canvasBounds">
    <rect x="10" y="10" width="80" height="80" fill="blue" />
  </svg>
</template>

<script setup>
import { ref } from 'vue';
const canvasBounds = ref('0 0 100 100');
</script>

Without .camel, the browser receives viewbox, which SVG parsers ignore. The modifier ensures the correct viewBox property is applied.