Common Vue.js Pitfalls
Most bugs that trip up developers new to Vue 3 — and more than a few experienced ones — trace back to a handful of recurring misunderstandings: losing reactivity by destructuring or reassigning incorrectly, mutating props directly, misusing :key in list rendering, or misjudging when reactive state is actually available during a component's lifecycle. None of these are exotic edge cases; they show up constantly in real codebases, which is exactly why recognizing them quickly is such a practical skill.
Cricket analogy: Just as young batsmen repeatedly fall into the trap of playing across the line to a good-length ball, Vue developers repeatedly stumble into the same handful of mistakes — destructuring away reactivity, mutating props directly, misusing :key in v-for, or reading state too early in the lifecycle — patterns recognizable once you've seen them a few times.
Losing reactivity through destructuring
The single most common reactivity pitfall is destructuring a reactive() object and expecting the extracted variables to stay reactive. Because reactive returns a Proxy that only intercepts access through the object itself, pulling a property out into a standalone variable copies its current value and severs the reactive connection — later mutations to the original object will not be reflected in that variable, and the UI bound to it will silently stop updating. The fix is either to keep accessing properties through the object (state.count) or to convert the object with toRefs() before destructuring, which produces individual refs that remain linked to the source.
Cricket analogy: Pulling a player's live strike rate out of the scoreboard feed and writing it on a static whiteboard means it stays frozen even as the real number updates on the big screen — reactive()'s Proxy only tracks changes through the object itself, so destructuring copies a snapshot; using toRefs() is like plugging a live sub-display directly into the scoreboard feed instead.
import { reactive, toRefs } from 'vue'
const state = reactive({ count: 0, label: 'clicks' })
// Pitfall: `count` is now a disconnected snapshot, not reactive
const { count } = state
// Fix: toRefs preserves the reactive link
const { count: countRef, label: labelRef } = toRefs(state)Another frequent trap: mutating props directly. Props establish a one-way data flow from parent to child, and Vue emits a runtime warning if a child component mutates a prop directly, because the parent is the actual source of truth and a silent local mutation would desync the two. The correct pattern is to emit an event asking the parent to update its own state, or to define local state derived from the prop. Mutating a *nested property* of an object prop (e.g. props.user.name = 'New Name') does not trigger Vue's direct-mutation warning the way reassigning the prop itself does, but it is just as much a violation of one-way data flow — treat prop objects as read-only at every depth, not just the top level.
Unstable `:key` in `v-for` and premature template ref access
Vue uses the :key attribute in v-for to match list items across re-renders so it can reuse, reorder, or correctly destroy DOM nodes and component instances instead of blindly patching by index. Omitting :key, or worse, using the array index as the key for a list that can be reordered, filtered, or have items inserted/removed from the middle, causes Vue to misattribute component state to the wrong item after the list changes — a classic symptom is form inputs or component-local state appearing to 'stick' to the wrong row after a delete or sort. A related class of bug involves template refs (obtained via ref combined with a matching ref="myEl" attribute): they are only populated after the component has mounted, because the underlying DOM elements don't exist until the initial render completes, so reading a template ref's .value inside setup()'s top-level code will find it null — the correct place to first use it is inside onMounted.
Cricket analogy: Vue's :key is like assigning each player a fixed shirt number instead of a batting-order slot — if you track fielders by lineup position and the order changes after a substitution, the wrong player's stats get attributed to the new occupant; similarly, a stadium's electronic scoreboard sign (template ref) only exists once the ground staff finish installing it (mounted), so checking it during setup finds nothing there yet.
<template>
<!-- Pitfall: index as key breaks identity when the list is reordered -->
<li v-for="(task, index) in tasks" :key="index">{{ task.title }}</li>
<!-- Fix: a stable, unique identifier from the data itself -->
<li v-for="task in tasks" :key="task.id">{{ task.title }}</li>
</template>Vue's ESLint plugin (eslint-plugin-vue) catches a number of these pitfalls automatically, including missing :key in v-for, direct prop mutation, and duplicate keys, making it a genuinely high-value addition to a Vue project's linting setup rather than a purely cosmetic tool. It won't catch reactivity-loss bugs from destructuring, though, since those require understanding data flow rather than static syntax.
- Destructuring a
reactive()object loses reactivity for the extracted variables; usetoRefs()before destructuring to preserve it. - Never mutate a prop directly, including nested properties of an object prop — emit an event or derive local state instead.
- Always use a stable, unique
:keyinv-for(like an item's id), never the array index for lists that can reorder or be filtered. - Template refs are
nulluntil after the component mounts; read them inonMountedor later, not during initial setup. - Mutating a nested property of an object prop bypasses Vue's direct-mutation warning but still breaks one-way data flow.
eslint-plugin-vuecatches several of these pitfalls automatically and is worth enabling in any real Vue project.
Practice what you learned
1. Why does destructuring a `reactive()` object cause the extracted variables to lose reactivity?
2. What is the correct way for a child component to respond to a need to change a value that was passed in as a prop?
3. Why is using the array index as `:key` in a `v-for` risky for a list that can be reordered or filtered?
4. When is a template ref's `.value` first guaranteed to be populated (non-null) for a DOM element?
5. Does Vue's direct-prop-mutation warning fire when a child mutates a nested property of an object prop (e.g. `props.user.name = 'X'`)?
Was this page helpful?
You May Also Like
reactive() and ref()
A deep dive into Vue 3's two core reactivity primitives — ref() for any value type and reactive() for objects — and when to use each.
List Rendering with v-for
Covers how v-for renders lists and objects in Vue templates, why the key attribute matters, and common performance and correctness pitfalls.
Props Explained
Explains how props pass data from parent to child components in Vue, covering declaration, validation, defaults, and the one-way data flow rule.
Vue.js Interview Questions
A curated set of commonly asked Vue 3 interview questions with model answers, covering reactivity, the Composition API, component communication, and performance.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics