Custom Directives in Vue

Welcome back! In the last lesson, you learned how to use dependency injection with provide and inject to share state and functions across your Vue application. This pattern helps you avoid prop drilling and keeps your codebase clean and scalable. As you continue to build more advanced and production-ready Vue apps, you will sometimes need to interact directly with the DOM or add custom behavior to elements in your templates. This is where custom directives come in.

In this lesson, you will learn how to create and use custom directives in Vue 3. You will see how directives allow you to extend HTML with your own reusable behaviors, such as automatically focusing an input field when a component is mounted. We will walk through a real-world example using a v-focus directive, show you how to register it globally, and demonstrate how to use it in a form component. By the end of this lesson, you will be able to create your own custom directives and apply them in your projects, making your templates more powerful and expressive.

Vue comes with a few built-in directives, like v-if, v-for, and v-model, which you have likely used many times. However, there are situations where you need to add your own custom behavior to DOM elements. Custom directives let you do exactly that. They are especially useful for low-level DOM manipulations that are not covered by Vue’s built-in features.

A custom directive in Vue is an object that can have several lifecycle hooks, such as created, beforeMount, mounted, beforeUpdate, updated, and unmounted. The most commonly used hook is mounted, which is called when the element is inserted into the DOM. This is the perfect place to perform actions like focusing an input, setting up event listeners, or integrating with third-party libraries.

For example, if you want an input field to automatically receive focus when it appears, you can create a custom directive that calls the focus() method on the element in the mounted hook. This approach keeps your templates clean and avoids repeating the same logic in multiple places.

Let’s look at how to create a simple but useful custom directive called v-focus. This directive will automatically focus an input element when it is mounted. The code for this directive is placed in src/directives/v-focus.js:

// A custom directive is an object with lifecycle hooks.
// The 'mounted' hook is called when the element is inserted into the DOM.
const vFocus = {
  mounted: (el) => {
    // `el` is the element the directive is bound to.
    // We can perform direct DOM manipulations here.
    el.focus();
  }
};

export default vFocus;

In this code, the directive is defined as an object with a mounted function. The function receives the DOM element as its first argument. When the element is added to the DOM, the function calls el.focus(), which brings the input field into focus automatically. This is a simple example, but it shows the power of custom directives for handling direct DOM tasks that are not easily managed with standard Vue features.

If you were to use this directive on an input field, the result would be that the input is focused as soon as it appears on the page, making it easier for users to start typing right away.