1---
2title: Refs in Arrays and Collections Require .value
3impact: MEDIUM
4impactDescription: Refs inside reactive arrays, Maps, or Sets are NOT auto-unwrapped like in reactive objects
5type: capability
6tags: [vue3, reactivity, ref, arrays, collections, unwrapping]
7---
8 
9# Refs in Arrays and Collections Require .value
10 
11**Impact: MEDIUM** - Unlike when a ref is a property of a reactive object, refs inside reactive arrays, Maps, and Sets are NOT automatically unwrapped. You must access them with `.value`, and forgetting this leads to silent bugs.
12 
13Vue only auto-unwraps refs when they are properties of reactive objects. When refs are elements in arrays or values in Maps/Sets, they remain as ref objects and require explicit `.value` access.
14 
15## Task Checklist
16 
17- [ ] Always use `.value` when accessing refs stored in reactive arrays
18- [ ] Always use `.value` when accessing refs stored in reactive Maps or Sets
19- [ ] Consider storing plain values instead of refs in collections to avoid confusion
20- [ ] Be aware of this when iterating over arrays containing refs
21 
22**Incorrect:**
23```javascript
24import { ref, reactive } from 'vue'
25 
26const books = reactive([ref('Vue 3 Guide')])
27const counts = reactive(new Map([['clicks', ref(0)]]))
28 
29// WRONG: Refs in arrays are NOT unwrapped
30console.log(books[0])        // Ref object, not 'Vue 3 Guide'
31books[0] = 'New Title'       // Replaces the ref, doesn't update it!
32 
33// WRONG: Refs in Maps are NOT unwrapped
34console.log(counts.get('clicks'))     // Ref object, not 0
35counts.get('clicks')++                // Does nothing useful
36```
37 
38**Correct:**
39```javascript
40import { ref, reactive } from 'vue'
41 
42const books = reactive([ref('Vue 3 Guide')])
43const counts = reactive(new Map([['clicks', ref(0)]]))
44 
45// CORRECT: Use .value for refs in arrays
46console.log(books[0].value)    // 'Vue 3 Guide'
47books[0].value = 'New Title'   // Updates the ref's value
48 
49// CORRECT: Use .value for refs in Maps
50console.log(counts.get('clicks').value)  // 0
51counts.get('clicks').value++             // Increments to 1
52```
53 
54```javascript
55// ALTERNATIVE: Just store plain values in collections (simpler)
56const books = reactive(['Vue 3 Guide', 'Vuex Handbook'])
57const counts = reactive(new Map([['clicks', 0]]))
58 
59// No .value needed - but changes to individual items aren't independently reactive
60console.log(books[0])            // 'Vue 3 Guide'
61console.log(counts.get('clicks')) // 0
62 
63// Mutations still trigger reactivity through the reactive wrapper
64books[0] = 'New Title'           // Works
65counts.set('clicks', counts.get('clicks') + 1)  // Works
66```
67 
68```vue
69<template>
70  <!-- In templates, refs in arrays also need special handling -->
71  <div v-for="(book, index) in books" :key="index">
72    <!-- If book is a ref, you'd need: -->
73    {{ book.value }}
74 
75    <!-- Or use computed to unwrap them first -->
76  </div>
77</template>
78```
79 
80## Reference
81- [Vue.js Reactivity Fundamentals - Caveat in Arrays and Collections](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-in-arrays-and-collections)
82