1---
2title: Directive Best Practices
3impact: MEDIUM
4impactDescription: Custom directives are powerful but easy to misuse; following patterns prevents leaks, invalid usage, and unclear abstractions
5type: best-practice
6tags: [vue3, directives, custom-directives, composition, typescript]
7---
8 
9# Directive Best Practices
10 
11**Impact: MEDIUM** - Directives are for low-level DOM access. Use them sparingly, keep them side-effect safe, and prefer components or composables when you need stateful or reusable UI behavior.
12 
13## Task List
14 
15- Use directives only when you need direct DOM access
16- Do not mutate directive arguments or binding objects
17- Clean up timers, listeners, and observers in `unmounted`
18- Register directives in `<script setup>` with the `v-` prefix
19- In TypeScript projects, type directive values and augment template directive types
20- Prefer components or composables for complex behavior
21 
22## Treat Directive Arguments as Read-Only
23 
24Directive bindings are not reactive storage. Don’t write to them.
25 
26```ts
27const vFocus = {
28  mounted(el, binding) {
29    // binding.value is read-only
30    el.focus()
31  }
32}
33```
34 
35## Avoid Directives on Components
36 
37Directives apply to DOM elements. When used on components, they attach to the root element and can break if the root changes.
38 
39**BAD:**
40```vue
41<MyInput v-focus />
42```
43 
44**GOOD:**
45```vue
46<!-- MyInput.vue -->
47<script setup>
48const vFocus = (el) => el.focus()
49</script>
50 
51<template>
52  <input v-focus />
53</template>
54```
55 
56## Clean Up Side Effects in `unmounted`
57 
58Any timers, listeners, or observers must be removed to avoid leaks.
59 
60```ts
61const vResize = {
62  mounted(el) {
63    const observer = new ResizeObserver(() => {})
64    observer.observe(el)
65    el._observer = observer
66  },
67  unmounted(el) {
68    el._observer?.disconnect()
69  }
70}
71```
72 
73## Prefer Function Shorthand for Single-Hook Directives
74 
75If you only need `mounted`/`updated`, use the function form.
76 
77```ts
78const vAutofocus = (el) => el.focus()
79```
80 
81## Use the `v-` Prefix and Script Setup Registration
82 
83```vue
84<script setup>
85const vFocus = (el) => el.focus()
86</script>
87 
88<template>
89  <input v-focus />
90</template>
91```
92 
93## Type Custom Directives in TypeScript Projects
94 
95Use `Directive<Element, ValueType>` so `binding.value` is typed, and augment Vue's template types so directives are recognized in SFC templates.
96 
97**BAD:**
98```ts
99// Untyped directive value and no template type augmentation
100export const vHighlight = {
101  mounted(el, binding) {
102    el.style.backgroundColor = binding.value
103  }
104}
105```
106 
107**GOOD:**
108```ts
109import type { Directive } from 'vue'
110 
111type HighlightValue = string
112 
113export const vHighlight = {
114  mounted(el, binding) {
115    el.style.backgroundColor = binding.value
116  }
117} satisfies Directive<HTMLElement, HighlightValue>
118 
119declare module 'vue' {
120  interface ComponentCustomProperties {
121    vHighlight: typeof vHighlight
122  }
123}
124```
125 
126## Handle SSR with `getSSRProps`
127 
128Directive hooks such as `mounted` and `updated` do not run during SSR. If a directive sets attributes/classes that affect rendered HTML, provide an SSR equivalent via `getSSRProps` to avoid hydration mismatches.
129 
130**BAD:**
131```ts
132const vTooltip = {
133  mounted(el, binding) {
134    el.setAttribute('data-tooltip', binding.value)
135    el.classList.add('has-tooltip')
136  }
137}
138```
139 
140**GOOD:**
141```ts
142const vTooltip = {
143  mounted(el, binding) {
144    el.setAttribute('data-tooltip', binding.value)
145    el.classList.add('has-tooltip')
146  },
147  getSSRProps(binding) {
148    return {
149      'data-tooltip': binding.value,
150      class: 'has-tooltip'
151    }
152  }
153}
154```
155 
156## Prefer Declarative Templates When Possible
157 
158If a standard attribute or binding works, use it instead of a directive.
159 
160## Decide Between Directives and Components
161 
162Use a directive for DOM-level behavior. Use a component when behavior affects structure, state, or rendering.
163