1---
2title: Variables in Script Setup Are Not Reactive by Default
3impact: HIGH
4impactDescription: Forgetting to wrap variables with ref() or reactive() causes silent reactivity failures in script setup
5type: gotcha
6tags: [vue3, sfc, script-setup, reactivity, ref, composition-api]
7---
8 
9# Variables in Script Setup Are Not Reactive by Default
10 
11**Impact: HIGH** - Unlike Options API's `data()` which automatically makes properties reactive, variables declared in `<script setup>` are plain JavaScript values. You must explicitly use `ref()` or `reactive()` to make them reactive. Forgetting this causes the UI to not update when values change.
12 
13## Task Checklist
14 
15- [ ] Always wrap primitive values (strings, numbers, booleans) with `ref()`
16- [ ] Use `reactive()` for objects when you don't need to reassign the whole object
17- [ ] Remember to access `.value` on refs in script (not needed in templates)
18- [ ] Use `computed()` from Vue, not a plain function, for derived reactive state
19 
20**Problematic Code:**
21```vue
22<script setup>
23// BAD: These are NOT reactive!
24let count = 0
25let message = 'Hello'
26let user = { name: 'John', age: 30 }
27 
28function increment() {
29  count++  // This change won't update the UI!
30}
31 
32function updateMessage() {
33  message = 'World'  // UI won't reflect this change!
34}
35</script>
36 
37<template>
38  <div>
39    <!-- Will always show initial values -->
40    <p>Count: {{ count }}</p>
41    <p>Message: {{ message }}</p>
42    <button @click="increment">Increment</button>
43    <button @click="updateMessage">Update</button>
44  </div>
45</template>
46```
47 
48**Correct Code:**
49```vue
50<script setup>
51import { ref, reactive, computed } from 'vue'
52 
53// GOOD: Primitives wrapped with ref()
54const count = ref(0)
55const message = ref('Hello')
56 
57// GOOD: Object with reactive()
58const user = reactive({ name: 'John', age: 30 })
59 
60// GOOD: Computed for derived state
61const doubleCount = computed(() => count.value * 2)
62 
63function increment() {
64  count.value++  // Use .value for refs in script
65}
66 
67function updateMessage() {
68  message.value = 'World'
69}
70 
71function updateUser() {
72  user.name = 'Jane'  // No .value needed for reactive objects
73}
74</script>
75 
76<template>
77  <div>
78    <!-- No .value needed in templates - Vue unwraps automatically -->
79    <p>Count: {{ count }}</p>
80    <p>Double: {{ doubleCount }}</p>
81    <p>Message: {{ message }}</p>
82    <p>User: {{ user.name }}</p>
83    <button @click="increment">Increment</button>
84  </div>
85</template>
86```
87 
88## Common Mistake: Plain Computed
89 
90```vue
91<script setup>
92import { ref } from 'vue'
93 
94const items = ref([1, 2, 3, 4, 5])
95 
96// BAD: Plain function, not reactive - won't update when items change
97const total = items.value.reduce((sum, n) => sum + n, 0)
98 
99// BAD: Arrow function - recalculates but Vue doesn't track it
100const getTotal = () => items.value.reduce((sum, n) => sum + n, 0)
101</script>
102 
103<template>
104  <!-- total never updates, getTotal works but isn't optimal -->
105  <p>Total: {{ total }}</p>
106</template>
107```
108 
109```vue
110<script setup>
111import { ref, computed } from 'vue'
112 
113const items = ref([1, 2, 3, 4, 5])
114 
115// GOOD: computed() tracks dependencies and caches result
116const total = computed(() => items.value.reduce((sum, n) => sum + n, 0))
117</script>
118 
119<template>
120  <p>Total: {{ total }}</p>  <!-- Updates when items change -->
121</template>
122```
123 
124## When to Use ref() vs reactive()
125 
126```vue
127<script setup>
128import { ref, reactive } from 'vue'
129 
130// Use ref() for:
131// - Primitives (string, number, boolean)
132// - Values you might reassign entirely
133const count = ref(0)
134const isLoading = ref(false)
135const selectedId = ref<number | null>(null)
136 
137// Use reactive() for:
138// - Objects/arrays you'll mutate but not reassign
139// - When you want to avoid .value
140const form = reactive({
141  name: '',
142  email: '',
143  errors: []
144})
145 
146// Gotcha: Can't reassign reactive objects
147const user = reactive({ name: 'John' })
148// user = { name: 'Jane' }  // This breaks reactivity!
149// user.name = 'Jane'       // This works
150 
151// Use ref() if you need to reassign objects
152const userData = ref({ name: 'John' })
153userData.value = { name: 'Jane' }  // This works
154</script>
155```
156 
157## Template Automatic Unwrapping
158 
159Vue automatically unwraps refs in templates:
160 
161```vue
162<script setup>
163import { ref } from 'vue'
164 
165const count = ref(0)
166const user = ref({ name: 'John' })
167</script>
168 
169<template>
170  <!-- All of these work - no .value needed -->
171  <p>{{ count }}</p>
172  <p>{{ user.name }}</p>
173  <input v-model="count" type="number">
174  <button @click="count++">Increment</button>
175</template>
176```
177 
178But in event handlers written inline, you might still need `.value`:
179 
180```vue
181<template>
182  <!-- This works (Vue handles it) -->
183  <button @click="count++">+1</button>
184 
185  <!-- For complex logic, .value may be needed -->
186  <button @click="() => { count.value = Math.max(0, count.value - 1) }">
187    -1 (min 0)
188  </button>
189</template>
190```
191 
192## Reference
193- [Vue.js Reactivity Fundamentals](https://vuejs.org/guide/essentials/reactivity-fundamentals.html)
194- [Vue.js ref()](https://vuejs.org/api/reactivity-core.html#ref)
195- [Vue.js reactive()](https://vuejs.org/api/reactivity-core.html#reactive)
196