Vue Academy · Lesson

Writing Custom Directives

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

Lesson 4 of 413 steps

Writing Custom Directives is a free Vue Academy lesson on CoddyKit. This is lesson 4 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Vue Academy learning path, and your progress syncs across the web and the CoddyKit app. The Vue Academy course includes 4 lessons in total.

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.

Answer it in the interactive lesson

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.

Free to start

Learn HTML with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 42
Lessons: 156

Start learning free View the full course

Frequently Asked Questions

Is the “Writing Custom Directives” lesson free?

Yes — any 3 lessons of the Vue Academy learning path, including “Writing Custom Directives”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Vue Academy course includes 4 lessons in total.

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, so you can start here or from the beginning and move at your own pace. This is lesson 4 of 4.

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