Vue Academy · Lesson

Writing Custom Directives

app.directive(), mounted/updated/unmounted hooks, directive arguments and modifiers.

Writing Custom Directives is a free Vue Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Vue Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

When Components Are Not Enough

Most reuse in Vue happens through components and composables. But some logic targets the raw DOM — autofocusing an input, integrating a non-Vue library, or measuring an element. Custom directives are built for exactly this.

A Minimal Directive

Register a directive on the app with app.directive. The mounted hook receives the element, so this directive focuses an input when it appears.

const app = createApp(App)
app.directive('focus', {
  mounted(el) { el.focus() }
})

Using the Directive

Apply it in a template with the v- prefix plus the registered name.

<template>
  <input v-focus />
</template>

Local Directives in script setup

Inside <script setup>, any top-level variable that starts with v and is camelCase becomes a usable directive. Name it vFocus and use it as v-focus.

<script setup>
const vFocus = {
  mounted: (el) => el.focus()
}
</script>

<template>
  <input v-focus />
</template>

The Binding Object

Every hook receives a binding object as its second argument. It carries the directive value, argument, and modifiers passed in the template.

app.directive('demo', {
  mounted(el, binding) {
    console.log(binding.value, binding.arg, binding.modifiers)
  }
})

Passing a Value

The expression after the equals sign becomes binding.value. Here a color is passed and applied to the element.

<!-- template -->
<p v-color="'red'">Hello</p>

<!-- directive -->
app.directive('color', {
  mounted(el, binding) { el.style.color = binding.value }
})

Passing an Argument

The part after the colon becomes binding.arg. It lets one directive behave differently based on a label.

<!-- v-pin:top means binding.arg === 'top' -->
<div v-pin:top="20"></div>

Using Modifiers

Modifiers appear after dots and arrive in binding.modifiers as a boolean map. Use them to tweak behavior.

<!-- v-pin.fixed -> binding.modifiers.fixed === true -->
<div v-pin.fixed="10"></div>

Directive Lifecycle Hooks

Directives have hooks that mirror component lifecycle: created, beforeMount, mounted, beforeUpdate, updated, beforeUnmount, and unmounted.

Reacting to Updates

The updated hook runs after the element re-renders. Compare binding.value with binding.oldValue to act only on real changes, and clean up in unmounted.

app.directive('color', {
  mounted(el, binding) { el.style.color = binding.value },
  updated(el, binding) {
    if (binding.value !== binding.oldValue) el.style.color = binding.value
  }
})

Directives vs Components

Prefer components for anything involving structure or state. Reach for directives only when you need low-level, direct DOM access that does not fit a component, like focus management or third-party DOM widgets.

Quick Check

Test your custom directive knowledge.

Recap

You learned to build custom directives:

Register globally with app.directive or locally as vName in script setup.
binding.value, binding.arg, and binding.modifiers pass data in.
Lifecycle hooks: created, beforeMount, mounted, beforeUpdate, updated, beforeUnmount, unmounted.
Use directives for low-level DOM work; prefer components otherwise.

Frequently asked questions

Is the “Writing Custom Directives” lesson free?

Yes — the full text of “Writing Custom Directives” is free to read here on the web, and the Vue Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Vue Academy course, upgrade to CoddyKit PRO.

What will I learn in “Writing Custom Directives”?

app.directive(), mounted/updated/unmounted hooks, directive arguments and modifiers. You practise Vue Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Vue Academy?

No prior experience is required. Vue Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Writing Custom Directives” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Vue Academy lesson?

Yes. Every Vue Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Vue Academy