1---
2title: Always Provide Unique Keys in v-for Loops
3impact: HIGH
4impactDescription: Missing or improper keys cause hard-to-debug bugs when list items have state, components, or animations
5type: gotcha
6tags: [vue3, v-for, list-rendering, key, state, components]
7---
8 
9# Always Provide Unique Keys in v-for Loops
10 
11**Impact: HIGH** - Without proper keys, Vue cannot track element identity when lists change. This causes component state loss, incorrect animations, form input values jumping between items, and bugs that are extremely difficult to debug.
12 
13The `key` attribute tells Vue how your data relates to the DOM elements it renders. When data ordering changes (via sort, filter, add, or remove), Vue uses keys to determine what to update, remove, or create. Without unique keys, Vue reuses DOM elements in-place which can cause one item's state to incorrectly appear on another item.
14 
15## Task Checklist
16 
17- [ ] Always provide `:key` with unique, stable identifiers (database IDs, UUIDs)
18- [ ] Never use array index as key - indices shift when items are added/removed
19- [ ] Use primitive values only (strings or numbers) - never use objects as keys
20- [ ] On `<template v-for>`, place the key on the `<template>` tag itself (Vue 3 change)
21- [ ] When using components in v-for, keys are mandatory, not optional
22 
23**Incorrect:**
24```html
25<!-- WRONG: No key provided -->
26<li v-for="item in items">{{ item.name }}</li>
27 
28<!-- WRONG: Using array index as key - shifts when list changes -->
29<li v-for="(item, index) in items" :key="index">
30  <input v-model="item.value" />
31</li>
32 
33<!-- WRONG: Object as key -->
34<li v-for="item in items" :key="item">{{ item.name }}</li>
35 
36<!-- WRONG (Vue 3): Key on child instead of template -->
37<template v-for="item in items">
38  <li :key="item.id">{{ item.name }}</li>
39</template>
40```
41 
42```javascript
43// Bug demonstration: Using index as key
44// Initial: ['Alice', 'Bob', 'Charlie'] at indices [0, 1, 2]
45// After removing 'Bob': ['Alice', 'Charlie'] at indices [0, 1]
46// Charlie now has index 1, so Vue reuses Bob's DOM/component state for Charlie!
47```
48 
49**Correct:**
50```html
51<!-- CORRECT: Unique identifier as key -->
52<li v-for="item in items" :key="item.id">
53  {{ item.name }}
54</li>
55 
56<!-- CORRECT: With components -->
57<MyComponent
58  v-for="item in items"
59  :key="item.id"
60  :item="item"
61/>
62 
63<!-- CORRECT (Vue 3): Key on template tag -->
64<template v-for="item in items" :key="item.id">
65  <li>{{ item.name }}</li>
66  <span>{{ item.description }}</span>
67</template>
68 
69<!-- CORRECT: With stateful elements -->
70<div v-for="user in users" :key="user.id">
71  <input v-model="user.email" />
72  <select v-model="user.role">
73    <option value="admin">Admin</option>
74    <option value="user">User</option>
75  </select>
76</div>
77```
78 
79## When Keys Are Critical
80 
81Keys are absolutely required when v-for loops contain:
82- Components with local state
83- Form elements (`<input>`, `<select>`, `<textarea>`)
84- Elements with initialization logic (mounted/created hooks)
85- Animations or transitions
86- Direct DOM manipulation
87 
88## Reference
89- [Vue.js List Rendering - Key](https://vuejs.org/guide/essentials/list.html#maintaining-state-with-key)
90- [Vue 3 Migration Guide - Key on Template](https://v3-migration.vuejs.org/breaking-changes/key-attribute)
91