The New Default. Your hub for building smart, fast, and sustainable AI software
Table of Contents
and 6 more
Vue directives decide when Vue creates, updates, hides or skips parts of the DOM, so choosing the right one is the cheapest performance work you can do in a Vue 3 app.
Three choices account for most of the gains: v-if versus v-show for conditional content, stable keys on v-for lists, and v-once or v-memo for sub-trees that rarely change.
This guide covers each of them, points out the directive advice that changed with the move from Vue 2 to Vue 3, and explains when directive tuning is the wrong place to look.
Executive Summary
Vue.js optimization with directives comes down to telling Vue how much work it can skip.
Use v-show for content that toggles often and v-if for content that rarely appears, give every stateful v-for item a unique, stable key, and reach for v-once or v-memo only in measured hot spots such as long lists. Older advice to use v-pre and v-cloak for speed doesn't hold for modern build-step Vue 3 apps.
Profile first: directive changes fix specific re-render problems, not a slow app in general.
What Are Vue Directives and Why Do They Affect Performance?
Vue directives are special v- attributes in a template that tell Vue how to render and update an element: whether it exists (v-if), whether it's visible (v-show), how many copies to create (v-for), and whether it ever needs to update again (v-once, v-memo). Each one translates into a different amount of work for Vue's renderer and the browser.
That's why two templates that look identical on screen can behave very differently under load. A misused directive rarely breaks an app outright. It shows up as a dashboard that stutters when filters change, a form that loses input when a list reorders, or a long table that freezes on every update. These are the problems users notice, and they usually trace back to a handful of directive decisions in the hottest components. For a broader view beyond templates, see our guide to proven Vue.js performance techniques.
v-if vs v-show: Which Is Faster in Vue.js?
Neither is faster in every case. The Vue docs put it this way: v-if has higher toggle costs, while v-show has higher initial render costs. Prefer v-show when something toggles very often, and v-if when the condition is unlikely to change at runtime.
The difference comes from what each directive does. v-if adds and removes the element from the DOM, destroying and re-creating its child components and event listeners on every toggle. It's also lazy: if the condition is false on first render, Vue renders nothing at all. v-show always renders the element and only switches its CSS display property, so toggling is cheap but you pay for the content upfront, even if the user never opens it.
Directive | What happens on toggle | Initial render cost | Best for |
|---|---|---|---|
v-if | Element and children are destroyed and re-created | Low when the condition starts false (nothing is rendered) | Rarely shown content: modals, admin-only panels, error states |
v-show | CSS | Always pays the full render cost | Frequently toggled content: tabs, dropdowns, accordions |
One practical trade-off: v-if resets component state on every toggle, while v-show preserves it. If a user fills in half a form inside a collapsible panel, v-show keeps their input when they close and reopen it. Sometimes that state behavior, not speed, should drive the choice.
How Should You Use Keys with v-for in Vue 3?
Give each item a unique, stable key that identifies the item itself, usually an ID from your data: :key="item.id". The Vue docs say keys should be primitives (strings or numbers), never objects.
Without keys, Vue uses an "in-place patch" strategy: when the order changes, it updates each element at its current position rather than moving elements around. That's efficient, but only safe when the list output doesn't depend on child component state or temporary DOM state, like form input values. Once it does, a missing or wrong key shows up as a bug, not just a slowdown.
Using the array index as a key is the most common way to get this wrong. An index is unique, but it describes a position, not an item, so after you insert, remove or reorder items, Vue matches the wrong DOM nodes to the wrong data:
<!-- Avoid for dynamic lists: index describes position, not identity -->
<li v-for="(item, index) in items" :key="index">{{ item.name }}</li>
<!-- Do this: a stable ID follows the item wherever it moves -->
<li v-for="item in items" :key="item.id">{{ item.name }}</li>For a static list of plain text that never reorders, the index (or Vue's default behavior) is fine. Save the discipline for lists with components, inputs, transitions or reordering.
Can You Use v-if and v-for on the Same Element?
Don't. In Vue 3, v-if has higher priority than v-for, so the v-if condition can't see the loop variable. The template below fails outright, because item is undefined when the condition is evaluated. (Vue 2 had the opposite precedence, which is why older tutorials still show this pattern.)
<!-- Breaks in Vue 3: v-if runs before v-for, so item is undefined -->
<li v-for="item in items" v-if="item.visible" :key="item.id">
{{ item.name }}
</li>Filter the list in a computed property instead. The computed value is cached and only recalculated when items changes, so the template loops over exactly what it needs to render:
<script setup>
import { computed, ref } from 'vue'
const items = ref([])
const visibleItems = computed(() =>
items.value.filter((item) => item.visible)
)
</script>
<template>
<ul>
<li v-for="item in visibleItems" :key="item.id">
{{ item.name }}
</li>
</ul>
</template>If you need to hide the whole list based on a condition, put v-if on a wrapping element or a <template> tag instead.
When Do v-once and v-memo Improve Vue Performance?
v-once and v-memo are the two built-in directives designed specifically for performance. Both tell Vue to skip updates for a part of the template, which matters most when that part is large and its parent re-renders often.
v-once renders an element or component once and treats it as static from then on, according to the Vue API reference. It suits content that depends on data at first render but never needs to change, such as a terms-of-service block or a product description loaded once:
<section v-once>
<h2>{{ product.name }}</h2>
<div v-html="product.longDescription" />
</section>v-memo (Vue 3.2+) skips updates for a sub-tree unless one of the values in its dependency array changes. The Vue docs describe it as a micro-optimization for performance-critical scenarios, most useful for large v-for lists of over 1,000 items. In this example, changing the selection re-renders only the two rows whose selected state changed:
<div
v-for="item in list"
:key="item.id"
v-memo="[item.id === selectedId]"
>
<p>{{ item.name }} – selected: {{ item.id === selectedId }}</p>
<!-- ...more child nodes -->
</div>The risk is stale UI. If the dependency array leaves out a value the sub-tree uses, Vue will skip updates that should happen, and nothing will warn you. Put v-memo on the same element as v-for (it doesn't work inside the loop), and add it only after a profiler shows that the list is the bottleneck. For lists in the thousands, list virtualization, which renders only the rows near the viewport, usually helps more than v-memo.
Do v-pre and v-cloak Speed Up a Vue App?
Not in a typical Vue 3 project. Both directives are often listed as optimizations, but their documented purposes are narrower:
v-pre tells Vue to skip compiling an element and its children. Its main use, per the Vue docs, is displaying raw mustache syntax, for example in documentation pages that show
{{ }}code. When templates are pre-compiled at build time, it won't make a measurable difference to runtime speed.v-cloak hides raw template syntax until a component mounts. The Vue docs state it's only needed in no-build-step setups, where templates are written directly in the HTML page. If your app uses single-file components and a bundler like Vite, you don't need it.
Keep both in your toolbox for those edge cases, but don't spend review time on them in a standard SPA.
When Should You Write a Custom Directive in Vue 3?
Write a custom directive only when you need low-level DOM access on plain elements, such as autofocusing an input, observing visibility for lazy loading, or integrating a DOM-only library. The Vue docs recommend built-in directives like v-bind wherever possible because they are more efficient and server-rendering friendly. For reusable stateful logic, use a composable instead.
When you do write one, keep the performance cost low:
Use the Vue 3 hooks (
created,beforeMount,mounted,beforeUpdate,updated,beforeUnmount,unmounted). Tutorials that mentionbindorinserteddescribe Vue 2, and Vue 2 reached end of life on December 31, 2023.Keep
updatedcheap. It runs every time the parent component updates, so comparebinding.valuewithbinding.oldValueand skip DOM work when nothing changed.Clean up in
unmounted: remove event listeners, disconnect observers and clear timers, or they'll leak memory as components come and go.Avoid using custom directives on components. They apply only to the root node, and on multi-root components Vue ignores them and logs a warning.
How Do You Know If Directives Are Your Performance Problem?
Measure before changing anything. Vue DevTools has a performance profiler, and setting app.config.performance = true adds Vue-specific markers to the Chrome DevTools Performance panel, as described in the Vue performance guide. Look for components that re-render far more often than expected, or a single update that takes tens of milliseconds.
If the problem is a big list, keys, v-memo and virtualization are the levers. If many child components update when only one changed, the fix is often props stability, passing each child a value that only changes when that child is affected, rather than a directive at all. And if the app is slow to load rather than slow to update, directive choices won't help; bundle size and data fetching will.
Key Takeaways
v-if has higher toggle costs; v-show has higher initial render costs. Choose based on how often content toggles.
Key v-for items by a stable ID, not the index, whenever items carry state or the list reorders.
Never put v-if and v-for on the same element in Vue 3; filter in a computed property.
v-once and v-memo skip updates, but a wrong v-memo dependency array produces silently stale UI.
v-pre and v-cloak aren't performance tools in build-step Vue 3 apps.
Directive Choices Are Small Decisions with Visible Results
Directive optimization means making a few deliberate choices in the components that do the most work, not sprinkling v-memo across a codebase: v-if or v-show based on how often content toggles, keys that follow the data, and update-skipping directives only where a profiler shows a real bottleneck. Teams that settle these conventions early, in code review and in shared component patterns, avoid most of the re-render bugs that are expensive to trace later. If your Vue app has outgrown its early performance assumptions, Monterail's Vue.js development team can help you audit it and decide what's worth fixing first.
Vue Directives Performance FAQ





