1---
2title: Template Ref Unwrapping Only Works for Top-Level Properties
3impact: MEDIUM
4impactDescription: Nested refs in template expressions render as [object Object] instead of their values
5type: capability
6tags: [vue3, reactivity, ref, template, unwrapping]
7---
8 
9# Template Ref Unwrapping Only Works for Top-Level Properties
10 
11**Impact: MEDIUM** - Vue only auto-unwraps refs that are top-level properties in the template render context. Nested refs (refs inside objects) are NOT unwrapped in expressions, causing `[object Object]` rendering or calculation errors.
12 
13This caveat trips up developers when they store refs inside reactive objects or plain objects and try to use them in template expressions like `{{ object.count + 1 }}`.
14 
15## Task Checklist
16 
17- [ ] Keep refs at the top level of your setup return or script setup
18- [ ] Destructure nested refs to top-level variables before using in expressions
19- [ ] Be aware that text interpolation `{{ object.ref }}` DOES unwrap, but expressions `{{ object.ref + 1 }}` do NOT
20- [ ] Consider restructuring data to avoid nested refs in templates
21 
22**Incorrect:**
23```vue
24<script setup>
25import { ref } from 'vue'
26 
27const count = ref(0)
28const object = { id: ref(1) }
29</script>
30 
31<template>
32  <!-- WRONG: Nested ref in expression - does NOT unwrap -->
33  <p>ID + 1 = {{ object.id + 1 }}</p>
34  <!-- Renders: "ID + 1 = [object Object]1" -->
35 
36  <!-- Surprisingly, plain interpolation DOES work -->
37  <p>ID = {{ object.id }}</p>
38  <!-- Renders: "ID = 1" (unwrapped because it's the final expression) -->
39</template>
40```
41 
42**Correct:**
43```vue
44<script setup>
45import { ref } from 'vue'
46 
47const count = ref(0)
48const object = { id: ref(1) }
49 
50// SOLUTION 1: Destructure to top-level
51const { id } = object
52</script>
53 
54<template>
55  <!-- CORRECT: Top-level ref unwraps in all expressions -->
56  <p>Count + 1 = {{ count + 1 }}</p>
57  <!-- Renders: "Count + 1 = 1" -->
58 
59  <!-- CORRECT: Destructured ref is now top-level -->
60  <p>ID + 1 = {{ id + 1 }}</p>
61  <!-- Renders: "ID + 1 = 2" -->
62</template>
63```
64 
65```vue
66<script setup>
67import { ref, computed } from 'vue'
68 
69const object = { id: ref(1) }
70 
71// SOLUTION 2: Use computed for derived values
72const idPlusOne = computed(() => object.id.value + 1)
73</script>
74 
75<template>
76  <!-- CORRECT: Computed handles the .value access -->
77  <p>ID + 1 = {{ idPlusOne }}</p>
78</template>
79```
80 
81```vue
82<script setup>
83import { reactive } from 'vue'
84 
85// SOLUTION 3: Use reactive object instead (refs inside reactive auto-unwrap)
86const object = reactive({ id: 1 })
87</script>
88 
89<template>
90  <!-- CORRECT: Plain reactive property works in expressions -->
91  <p>ID + 1 = {{ object.id + 1 }}</p>
92</template>
93```
94 
95```javascript
96// WHY this happens:
97// - Template compilation only adds .value to top-level identifiers
98// - {{ count + 1 }} compiles to: count.value + 1
99// - {{ object.id + 1 }} compiles to: object.id + 1 (no .value added!)
100// - Plain {{ object.id }} has special handling for display purposes
101```
102 
103## Reference
104- [Vue.js Reactivity Fundamentals - Caveat when Unwrapping in Templates](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-when-unwrapping-in-templates)
105