⚡ Vue Directives and Event Handling

What Are Directives?

Directives are special attributes with a v- prefix that apply reactive behavior to the DOM. They are Vue's way of letting you declaratively connect your data to what appears on screen — you describe the relationship once, and Vue keeps the DOM in sync as the data changes.

💡 An analogy: A directive is a standing instruction you pin to an HTML element — "show yourself only when the user is an admin," "repeat once per item in this list," "keep your value tied to this variable." You set the rule; Vue enforces it continuously.

Core Directives

v-bind — bind an attribute to an expression

The most-used directive. It ties any HTML attribute to a reactive value. The shorthand is a leading colon:

<!-- Full and shorthand syntax -->
<img v-bind:src="imageUrl" v-bind:alt="caption">
<img :src="imageUrl" :alt="caption">

<!-- Toggle classes with object syntax -->
<div :class="{ active: isActive, error: hasError }">Status</div>

<!-- Inline styles from data -->
<div :style="{ color: textColor, fontSize: size + 'px' }">Styled</div>

v-for — render a list

Repeats an element once per item. Always pair it with a unique :key so Vue can track identity efficiently:

<li v-for="item in items" :key="item.id">{{ item.name }}</li>

<!-- With an index -->
<li v-for="(item, i) in items" :key="item.id">{{ i + 1 }}. {{ item.name }}</li>

<!-- Over an object's entries -->
<li v-for="(value, key) in user" :key="key">{{ key }}: {{ value }}</li>

v-if vs v-show

Both control whether an element is visible, but they work differently under the hood.

<div v-if="userType === 'admin'">Admin panel</div>
<div v-else-if="userType === 'editor'">Editor tools</div>
<div v-else>Standard view</div>

<div v-show="isVisible">I stay in the DOM, just hidden with display:none</div>

Two-Way Binding with v-model

v-model creates a two-way binding on form inputs: the input reflects your data, and typing updates your data. It works on text inputs, textareas, checkboxes, radios, and selects.

<input v-model="message">
<p>Message: {{ message }}</p>

<input type="checkbox" v-model="agreed">
<select v-model="choice">
  <option disabled value="">Please choose</option>
  <option>A</option>
  <option>B</option>
</select>

Under the hood, v-model is syntactic sugar for a :value binding plus an @input listener:

<!-- This… -->
<input v-model="searchText">

<!-- …is roughly this -->
<input :value="searchText" @input="searchText = $event.target.value">

Useful modifiers

<input v-model.trim="username">      <!-- strip surrounding whitespace -->
<input v-model.number="age">         <!-- cast the value to a number -->
<input v-model.lazy="note">          <!-- sync on change, not every keystroke -->

Event Handling with v-on

The v-on directive listens for DOM events and runs code when they fire. Its shorthand is @:

<button v-on:click="count++">Add 1</button>
<button @click="count++">Add 1</button>

<!-- Call a method -->
<button @click="greet">Greet</button>

<script setup>
import { ref } from 'vue';

const count = ref(0);
const name = ref('Vue');

function greet() {
  alert(`Hello ${name.value}!`);
}
</script>

To access the native event object while also passing arguments, use the special $event variable:

<button @click="warn('Careful!', $event)">Submit</button>

<script setup>
function warn(message, event) {
  event.preventDefault();
  console.log(event.target.tagName);
  alert(message);
}
</script>

Event Modifiers

Modifiers are suffixes that handle common event chores for you, so your handler stays focused on business logic instead of DOM plumbing:

<button @click.stop="doThis">Stop propagation</button>
<form @submit.prevent="onSubmit">No page reload</form>
<a @click.stop.prevent="doThat">Chain them</a>
<button @click.once="init">Fire only once</button>

<!-- Key modifiers -->
<input @keyup.enter="submit">
<input @keyup.alt.enter="clearForm">

Custom Component Events

Props send data down; events send messages up. A child emits a named event with emit(), and the parent listens for it with @event-name. This is the other half of the "props down, events up" contract.

Child emits

<template>
  <button @click="add">{{ count }}</button>
</template>

<script setup>
import { ref } from 'vue';

const count = ref(0);
const emit = defineEmits(['increment']);

function add() {
  count.value++;
  emit('increment', count.value);   // notify the parent, with a payload
}
</script>

Parent listens

<template>
  <h2>Parent total: {{ total }}</h2>
  <CounterButton @increment="onIncrement" />
</template>

<script setup>
import { ref } from 'vue';
import CounterButton from './CounterButton.vue';

const total = ref(0);
function onIncrement(childValue) {
  total.value = childValue;
}
</script>

You can also validate emitted events by passing an object to defineEmits, which documents the payload shape and warns on misuse:

const emit = defineEmits({
  increment: null,                                  // no validation
  submit: (payload) => {                            // validated
    if (!payload.email) {
      console.warn('submit event needs an email');
      return false;
    }
    return true;
  }
});

Custom Directives

When the built-in directives aren't enough for a low-level DOM task, you can write your own. A custom directive is an object of lifecycle hooks that receive the raw element.

// A simple global directive: autofocus an element on mount
app.directive('focus', {
  mounted(el) {
    el.focus();
  }
});

<input v-focus>   <!-- focused automatically when it appears -->

Directives can also read arguments, modifiers, and a value via the binding object:

app.directive('tooltip', {
  mounted(el, binding) {
    const position = binding.arg || 'top';      // v-tooltip:bottom
    const text = binding.value || 'Tooltip';    // v-tooltip="'Help'"
    const onClick = binding.modifiers.click;    // v-tooltip.click

    const tip = document.createElement('div');
    tip.className = `tooltip tooltip-${position}`;
    tip.textContent = text;
    el.appendChild(tip);

    const show = () => tip.classList.add('visible');
    const hide = () => tip.classList.remove('visible');
    if (onClick) {
      el.addEventListener('click', () => tip.classList.toggle('visible'));
    } else {
      el.addEventListener('mouseenter', show);
      el.addEventListener('mouseleave', hide);
    }
  }
});

Common real-world custom directives include autofocus, click-outside detection for dropdowns, infinite-scroll triggers, and permission-based visibility. Directive hooks (created, mounted, updated, unmounted, and their before* variants) mirror the component lifecycle.

Hands-on Exercise

<script setup>
import { reactive, ref } from 'vue';

const form = reactive({ name: '', email: '', message: '' });
const errors = reactive({ name: '', email: '', message: '' });
const isSubmitting = ref(false);

function validate() {
  errors.name = errors.email = errors.message = '';
  let ok = true;

  if (!form.name) { errors.name = 'Name is required'; ok = false; }
  if (!form.email) { errors.email = 'Email is required'; ok = false; }
  else if (!/^\S+@\S+\.\S+$/.test(form.email)) {
    errors.email = 'Enter a valid email'; ok = false;
  }
  if (form.message.length < 10) {
    errors.message = 'Message must be at least 10 characters'; ok = false;
  }
  return ok;
}

async function submit() {
  if (!validate()) return;
  isSubmitting.value = true;
  try {
    await new Promise((r) => setTimeout(r, 1000)); // fake API call
    form.name = form.email = form.message = '';
    alert('Sent!');
  } finally {
    isSubmitting.value = false;
  }
}
</script>

Summary & Quiz

📚 Further Reading

• Vue — Template Syntax
• Vue — Event Handling
• Vue — Form Input Bindings
• Vue — Component Events
• Vue — Custom Directives

🚀 What's Next?

You've now covered Vue's essentials end to end. Next we broaden the view with an overview of Angular — a very different, more opinionated framework — so you can weigh the trade-offs between the major front-end options.