Custom directives let you directly manipulate DOM elements in a reusable way. While components are for reusing UI logic, custom directives are for reusing low-level DOM manipulation - things like auto-focus, click-outside detection, tooltips, and lazy loading.
| Hook | When called |
|---|---|
| created | Before element's attributes/event listeners are applied |
| beforeMount | Before element is inserted into DOM |
| mounted | After element is inserted into DOM |
| beforeUpdate | Before the component updates |
| updated | After the component and children update |
| beforeUnmount | Before element is removed |
| unmounted | After element is removed |
// directives/index.js
// v-focus - auto-focus an input
export const vFocus = {
mounted(el) {
el.focus()
}
}
// v-click-outside - detect clicks outside an element
export const vClickOutside = {
mounted(el, binding) {
el._clickOutsideHandler = (event) => {
if (!el.contains(event.target)) {
binding.value(event) // call the provided function
}
}
document.addEventListener('click', el._clickOutsideHandler)
},
unmounted(el) {
document.removeEventListener('click', el._clickOutsideHandler)
}
}
// v-tooltip - show tooltip on hover
export const vTooltip = {
mounted(el, binding) {
const tooltip = document.createElement('div')
tooltip.className = 'tooltip'
tooltip.textContent = binding.value
tooltip.style.cssText = `
position: absolute; background: #333; color: white;
padding: 4px 8px; border-radius: 4px; font-size: 12px;
pointer-events: none; opacity: 0; transition: opacity 0.2s;
white-space: nowrap; z-index: 1000;
`
document.body.appendChild(tooltip)
el._tooltip = tooltip
el._showTooltip = () => {
const rect = el.getBoundingClientRect()
tooltip.style.left = rect.left + 'px'
tooltip.style.top = (rect.top - 30 + window.scrollY) + 'px'
tooltip.style.opacity = '1'
}
el._hideTooltip = () => { tooltip.style.opacity = '0' }
el.addEventListener('mouseenter', el._showTooltip)
el.addEventListener('mouseleave', el._hideTooltip)
},
updated(el, binding) {
el._tooltip.textContent = binding.value
},
unmounted(el) {
el.removeEventListener('mouseenter', el._showTooltip)
el.removeEventListener('mouseleave', el._hideTooltip)
el._tooltip.remove()
}
}
// v-lazy - lazy load images
export const vLazy = {
mounted(el, binding) {
const observer = new IntersectionObserver(([entry]) => {
if (entry.isIntersecting) {
el.src = binding.value
observer.disconnect()
}
}, { threshold: 0.1 })
observer.observe(el)
el._observer = observer
},
unmounted(el) {
el._observer?.disconnect()
}
}
// v-highlight - highlight text
export const vHighlight = {
mounted(el, binding) {
el.style.backgroundColor = binding.value || 'yellow'
},
updated(el, binding) {
el.style.backgroundColor = binding.value || 'yellow'
}
}
// Register globally in main.js:
// app.directive('focus', vFocus)
// app.directive('click-outside', vClickOutside)
// app.directive('tooltip', vTooltip)<template>
<div>
<!-- v-focus - auto-focus on mount -->
<input v-focus placeholder="I'm auto-focused!" />
<!-- v-click-outside - close dropdown when clicking outside -->
<div class="dropdown" v-click-outside="closeDropdown">
<button @click="isOpen = !isOpen">Menu</button>
<ul v-if="isOpen">
<li>Option 1</li>
<li>Option 2</li>
</ul>
</div>
<!-- v-tooltip - show tooltip on hover -->
<button v-tooltip="'Click to save your changes'">Save</button>
<button v-tooltip="tooltipText">Dynamic tooltip</button>
<!-- v-lazy - lazy load image -->
<img v-lazy="'/images/large-photo.jpg'" alt="Lazy loaded" />
<!-- v-highlight with value -->
<p v-highlight="'#ffeb3b'">This text is highlighted yellow</p>
<p v-highlight="'#e3f2fd'">This text is highlighted blue</p>
<!-- Local directive (in <script setup>, prefix with v) -->
<input v-auto-resize />
</div>
</template>
<script setup>
import { ref } from 'vue'
import { vFocus, vClickOutside, vTooltip, vLazy, vHighlight } from '@/directives'
const isOpen = ref(false)
const tooltipText = ref('Hello from Vue!')
function closeDropdown() {
isOpen.value = false
}
// Local directive - defined in <script setup>, no registration needed
// Just name it vSomething and use as v-something
const vAutoResize = {
mounted(el) {
el.style.resize = 'none'
el.style.overflow = 'hidden'
const resize = () => {
el.style.height = 'auto'
el.style.height = el.scrollHeight + 'px'
}
el.addEventListener('input', resize)
el._resize = resize
},
unmounted(el) {
el.removeEventListener('input', el._resize)
}
}
</script>created, beforeMount, mounted, beforeUpdate, updated, beforeUnmount, and unmounted expose different points in the host element lifetime. DOM measurement and focus need a mounted element, while listener removal and observer disconnection belong in unmounted. Keep per-element state on a WeakMap or another ownership mechanism rather than one shared mutable variable.
The binding object exposes value, oldValue, argument, modifiers, and the directive expression. Validate the accepted value shape and update only when a meaningful value changed. A click-outside directive, for example, must handle a replaced callback without registering duplicate document listeners.
A directive is appropriate for low-level behavior attached to one element, such as focus, intersection observation, or a third-party DOM integration. Reusable state, rendering, business rules, or behavior spanning several elements is clearer in a component or composable. Guard browser-only APIs during server rendering and test repeated mount, update, and unmount cycles.
A click-outside directive usually attaches a listener to document, not only to the element. If that listener is not removed in unmounted, it can keep firing after the component is gone, close the wrong menu, or leak memory across route changes.
Use a directive when you are adding behavior to an existing element without owning the markup: focus, click-outside, lazy loading, tooltip positioning, or small DOM integrations. Use a component when the abstraction owns structure, slots, props, emits, and styling.
The directive can only focus an element after that element exists in the DOM. If the input is behind v-if, the element may be created later than the moment you expected. Put first-focus logic in mounted, and use updated or a watcher when focus depends on a later condition.
Explore 500+ free tutorials across 20+ languages and frameworks.