1---
2name: Custom Directives
3description: Create reusable directives for low-level DOM manipulation
4---
5 
6# Custom Directives
7 
8Custom directives provide low-level DOM access for reusable behavior.
9 
10## When to Use
11 
12Use custom directives when:
13 
14- You need direct DOM manipulation
15- The behavior can't be achieved with components or composables
16- You need to apply behavior to native elements
17 
18## Basic Example
19 
20```vue
21<script setup lang="ts">
22// v-focus directive
23const vFocus = {
24  mounted: (el: HTMLElement) => el.focus()
25}
26</script>
27 
28<template>
29  <input v-focus />
30</template>
31```
32 
33## Directive Hooks
34 
35```ts
36const myDirective = {
37  // Before element attributes/listeners are applied
38  created(el, binding, vnode) {},
39 
40  // Before element is inserted into DOM
41  beforeMount(el, binding, vnode) {},
42 
43  // After element and children are mounted
44  mounted(el, binding, vnode) {},
45 
46  // Before parent component updates
47  beforeUpdate(el, binding, vnode, prevVnode) {},
48 
49  // After parent component updates
50  updated(el, binding, vnode, prevVnode) {},
51 
52  // Before parent component unmounts
53  beforeUnmount(el, binding, vnode) {},
54 
55  // After parent component unmounts
56  unmounted(el, binding, vnode) {}
57}
58```
59 
60## Hook Arguments
61 
62```ts
63interface DirectiveBinding<T = any> {
64  value: T           // v-my-dir="value"
65  oldValue: T        // Previous value (beforeUpdate/updated only)
66  arg?: string       // v-my-dir:arg
67  modifiers: Record<string, boolean>  // v-my-dir.foo.bar → { foo: true, bar: true }
68  instance: ComponentPublicInstance   // Component using the directive
69  dir: ObjectDirective               // Directive definition object
70}
71```
72 
73Example usage:
74 
75```vue-html
76<div v-example:foo.bar="baz">
77```
78 
79```ts
80// binding object:
81{
82  arg: 'foo',
83  modifiers: { bar: true },
84  value: /* value of baz */,
85  oldValue: /* previous value */
86}
87```
88 
89## Function Shorthand
90 
91When you only need `mounted` and `updated` with same behavior:
92 
93```ts
94// Full form
95const vColor = {
96  mounted(el, binding) {
97    el.style.color = binding.value
98  },
99  updated(el, binding) {
100    el.style.color = binding.value
101  }
102}
103 
104// Shorthand (same behavior)
105const vColor = (el: HTMLElement, binding: DirectiveBinding<string>) => {
106  el.style.color = binding.value
107}
108```
109 
110## Global Registration
111 
112```ts
113// main.ts
114const app = createApp(App)
115 
116app.directive('focus', {
117  mounted: (el) => el.focus()
118})
119 
120// Shorthand
121app.directive('color', (el, binding) => {
122  el.style.color = binding.value
123})
124```
125 
126## Object Literals
127 
128Pass multiple values:
129 
130```vue-html
131<div v-demo="{ color: 'white', text: 'hello' }">
132```
133 
134```ts
135const vDemo = (el: HTMLElement, binding: DirectiveBinding<{ color: string; text: string }>) => {
136  console.log(binding.value.color) // 'white'
137  console.log(binding.value.text)  // 'hello'
138}
139```
140 
141## Dynamic Arguments
142 
143```vue-html
144<div v-my-directive:[dynamicArg]="value">
145```
146 
147## Practical Examples
148 
149### v-click-outside
150 
151```ts
152const vClickOutside = {
153  mounted(el: HTMLElement, binding: DirectiveBinding<() => void>) {
154    el._clickOutside = (event: MouseEvent) => {
155      if (!el.contains(event.target as Node)) {
156        binding.value()
157      }
158    }
159    document.addEventListener('click', el._clickOutside)
160  },
161  unmounted(el: HTMLElement) {
162    document.removeEventListener('click', el._clickOutside)
163  }
164}
165```
166 
167### v-tooltip
168 
169```ts
170const vTooltip = {
171  mounted(el: HTMLElement, binding: DirectiveBinding<string>) {
172    el.setAttribute('title', binding.value)
173  },
174  updated(el: HTMLElement, binding: DirectiveBinding<string>) {
175    el.setAttribute('title', binding.value)
176  }
177}
178```
179 
180### v-permission
181 
182```ts
183const vPermission = {
184  mounted(el: HTMLElement, binding: DirectiveBinding<string>) {
185    if (!hasPermission(binding.value)) {
186      el.parentNode?.removeChild(el)
187    }
188  }
189}
190```
191 
192## TypeScript: Global Directives
193 
194```ts
195// directives/highlight.ts
196import type { Directive } from 'vue'
197 
198export type HighlightDirective = Directive<HTMLElement, string>
199 
200declare module 'vue' {
201  export interface ComponentCustomProperties {
202    vHighlight: HighlightDirective
203  }
204}
205 
206export default {
207  mounted: (el, binding) => {
208    el.style.backgroundColor = binding.value
209  }
210} satisfies HighlightDirective
211```
212 
213## Usage on Components
214 
215⚠️ **Not recommended** - directives apply to root element, which can be unpredictable with multi-root components.
216 
217```vue-html
218<!-- Applies to MyComponent's root element -->
219<MyComponent v-my-directive />
220```
221 
222<!--
223Source references:
224- https://vuejs.org/guide/reusability/custom-directives.html
225-->
226