Common Vue.js Pitfalls

Analogy categoryAnalogies

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.

javascript

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.

vue

<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; use toRefs() 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 :key in v-for (like an item's id), never the array index for lists that can reorder or be filtered.
Template refs are null until after the component mounts; read them in onMounted or 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-vue catches 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?

Vue.js Interview Questions

Vue.js Quick Reference

Related Study Notes in Web Development

Browse all study notes

Web Development

WebSockets Study Notes

Web Development · 30 topics

Web Development

WebAssembly Study Notes

WebAssembly · 30 topics

Web Development

gRPC Study Notes

Protocol Buffers · 30 topics

Web Development

Spring Boot Study Notes

Java · 30 topics

Web Development

Flask Study Notes

Python · 30 topics

Web Development

Django Study Notes

Python · 30 topics

Topics covered

#JavaScript#VueJsStudyNotes#WebDevelopment#CommonVueJsPitfalls#Common#Vue#Pitfalls#Losing#StudyNotes#SkillVeris

Common Vue.js Pitfalls