1---
2title: Reactivity Core Patterns (ref, reactive, shallowRef, computed, watch)
3impact: MEDIUM
4impactDescription: Clear reactivity choices keep state predictable and reduce unnecessary updates in Vue 3 apps
5type: efficiency
6tags: [vue3, reactivity, ref, reactive, shallowRef, computed, watch, watchEffect, external-state, best-practice]
7---
8 
9# Reactivity Core Patterns (ref, reactive, shallowRef, computed, watch)
10 
11**Impact: MEDIUM** - Choose the right reactive primitive first, derive with `computed`, and use watchers only for side effects.
12 
13This reference covers the core reactivity decisions for local state, external data, derived values, and effects.
14 
15## Task List
16 
17- Declare reactive state correctly
18  - Always use `shallowRef()` instead of `ref()` for primitive values
19  - Choose the correct reactive declaration method for objects/arrays/map/set
20- Follow best practices for `reactive`
21  - Avoid destructuring from `reactive()` directly
22  - Watch correctly for `reactive`
23- Follow best practices for `computed`
24  - Prefer `computed` over watcher-assigned derived refs
25  - Keep filtered/sorted derivations out of templates
26  - Use `computed` for reusable class/style logic
27  - Keep computed getters pure (no side effects) and put side effects in watchers
28- Follow best practices for watchers
29  - Use `immediate: true` instead of duplicate initial calls
30  - Clean up async effects for watchers
31 
32## Declare reactive state correctly
33 
34### Always use `shallowRef()` instead of `ref()` for primitive values (string, number, boolean, null, etc.) for better performance.
35 
36**Incorrect:**
37```ts
38import { ref } from 'vue'
39const count = ref(0)
40```
41 
42**Correct:**
43```ts
44import { shallowRef } from 'vue'
45const count = shallowRef(0)
46```
47 
48### Choose the correct reactive declaration method for objects/arrays/map/set
49 
50Use `ref()` when you often **replace the entire value** (`state.value = newObj`) and still want deep reactivity inside it, usually used for:
51 
52- Frequently reassigned state (replace fetched object/list, reset to defaults, switch presets).
53- Composable return values where updates happen mostly via `.value` reassignment.
54 
55Use `reactive()` when you mainly **mutate properties** and full replacement is uncommon, usually used for:
56 
57- “Single state object” patterns (stores/forms): `state.count++`, `state.items.push(...)`, `state.user.name = ...`.
58- Situations where you want to avoid `.value` and update nested fields in place.
59 
60```ts
61import { reactive } from 'vue'
62 
63const state = reactive({
64  count: 0,
65  user: { name: 'Alice', age: 30 }
66})
67 
68state.count++ // ✅ reactive
69state.user.age = 31 // ✅ reactive
70// ❌ avoid replacing the reactive object reference:
71// state = reactive({ count: 1 })
72```
73 
74Use `shallowRef()` when the value is **opaque / should not be proxied** (class instances, external library objects, very large nested data) and you only want updates to trigger when you **replace** `state.value` (no deep tracking), usually used for:
75 
76- Storing external instances/handles (SDK clients, class instances) without Vue proxying internals.
77- Large data where you update by replacing the root reference (immutable-style updates).
78 
79```ts
80import { shallowRef } from 'vue'
81 
82const user = shallowRef({ name: 'Alice', age: 30 })
83 
84user.value.age = 31 // ❌ not reactive
85user.value = { name: 'Bob', age: 25 } // ✅ triggers update
86```
87 
88Use `shallowReactive()` when you want **only top-level properties** reactive; nested objects remain raw, usually used for:
89 
90- Container objects where only top-level keys change and nested payloads should stay unmanaged/unproxied.
91- Mixed structures where Vue tracks the wrapper object, but not deeply nested or foreign objects.
92 
93```ts
94import { shallowReactive } from 'vue'
95 
96const state = shallowReactive({
97  count: 0,
98  user: { name: 'Alice', age: 30 }
99})
100 
101state.count++ // ✅ reactive
102state.user.age = 31 // ❌ not reactive
103```
104 
105## Best practices for `reactive`
106 
107### Avoid destructuring from `reactive()` directly
108 
109**BAD:**
110 
111```ts
112import { reactive } from 'vue'
113 
114const state = reactive({ count: 0 })
115const { count } = state // ❌ disconnected from reactivity
116```
117 
118### Watch correctly for reactive
119 
120**BAD:**
121 
122passing a non-getter value into `watch()`
123 
124```ts
125import { reactive, watch } from 'vue'
126 
127const state = reactive({ count: 0 })
128 
129// ❌ watch expects a getter, ref, reactive object, or array of these
130watch(state.count, () => { /* ... */ })
131```
132 
133**GOOD:**
134 
135preserve reactivity with `toRefs()` and use a getter for `watch()`
136 
137```ts
138import { reactive, toRefs, watch } from 'vue'
139 
140const state = reactive({ count: 0 })
141const { count } = toRefs(state) // ✅ count is a ref
142 
143watch(count, () => { /* ... */ }) // ✅
144watch(() => state.count, () => { /* ... */ }) // ✅
145```
146 
147## Best practices for `computed`
148 
149### Prefer `computed` over watcher-assigned derived refs
150 
151**BAD:**
152```ts
153import { ref, watchEffect } from 'vue'
154 
155const items = ref([{ price: 10 }, { price: 20 }])
156const total = ref(0)
157 
158watchEffect(() => {
159  total.value = items.value.reduce((sum, item) => sum + item.price, 0)
160})
161```
162 
163**GOOD:**
164```ts
165import { ref, computed } from 'vue'
166 
167const items = ref([{ price: 10 }, { price: 20 }])
168const total = computed(() =>
169  items.value.reduce((sum, item) => sum + item.price, 0)
170)
171```
172 
173### Keep filtered/sorted derivations out of templates
174 
175**BAD:**
176```vue
177<template>
178  <li v-for="item in items.filter(item => item.active)" :key="item.id">
179    {{ item.name }}
180  </li>
181 
182  <li v-for="item in getSortedItems()" :key="item.id">
183    {{ item.name }}
184  </li>
185</template>
186 
187<script setup>
188import { ref } from 'vue'
189 
190const items = ref([
191  { id: 1, name: 'B', active: true },
192  { id: 2, name: 'A', active: false }
193])
194 
195function getSortedItems() {
196  return [...items.value].sort((a, b) => a.name.localeCompare(b.name))
197}
198</script>
199```
200 
201**GOOD:**
202```vue
203<script setup>
204import { ref, computed } from 'vue'
205 
206const items = ref([
207  { id: 1, name: 'B', active: true },
208  { id: 2, name: 'A', active: false }
209])
210 
211const visibleItems = computed(() =>
212  items.value
213    .filter(item => item.active)
214    .sort((a, b) => a.name.localeCompare(b.name))
215)
216</script>
217 
218<template>
219  <li v-for="item in visibleItems" :key="item.id">
220    {{ item.name }}
221  </li>
222</template>
223```
224 
225### Use `computed` for reusable class/style logic
226 
227**BAD:**
228```vue
229<template>
230  <button :class="{ btn: true, 'btn-primary': type === 'primary' && !disabled, 'btn-disabled': disabled }">
231    {{ label }}
232  </button>
233</template>
234```
235 
236**GOOD:**
237```vue
238<script setup>
239import { computed } from 'vue'
240 
241const props = defineProps({
242  type: { type: String, default: 'primary' },
243  disabled: Boolean,
244  label: String
245})
246 
247const buttonClasses = computed(() => ({
248  btn: true,
249  [`btn-${props.type}`]: !props.disabled,
250  'btn-disabled': props.disabled
251}))
252</script>
253 
254<template>
255  <button :class="buttonClasses">
256    {{ label }}
257  </button>
258</template>
259```
260 
261### Keep computed getters pure (no side effects) and put side effects in watchers instead
262 
263A computed getter should only derive a value. No mutation, no API calls, no storage writes, no event emits.
264([Reference](https://vuejs.org/guide/essentials/computed.html#best-practices))
265 
266**BAD:**
267 
268side effects inside computed
269 
270```ts
271const count = ref(0)
272 
273const doubled = computed(() => {
274  // ❌ side effect
275  if (count.value > 10) console.warn('Too big!')
276  return count.value * 2
277})
278```
279 
280**GOOD:**
281 
282pure computed + `watch()` for side effects
283 
284```ts
285const count = ref(0)
286const doubled = computed(() => count.value * 2)
287 
288watch(count, (value) => {
289  if (value > 10) console.warn('Too big!')
290})
291```
292 
293## Best practices for watchers
294 
295### Use `immediate: true` instead of duplicate initial calls
296 
297**BAD:**
298```ts
299import { ref, watch, onMounted } from 'vue'
300 
301const userId = ref(1)
302 
303function loadUser(id) {
304  // ...
305}
306 
307onMounted(() => loadUser(userId.value))
308watch(userId, (id) => loadUser(id))
309```
310 
311**GOOD:**
312```ts
313import { ref, watch } from 'vue'
314 
315const userId = ref(1)
316 
317watch(
318  userId,
319  (id) => loadUser(id),
320  { immediate: true }
321)
322```
323 
324### Clean up async effects for watchers
325 
326When reacting to rapid changes (search boxes, filters), cancel the previous request.
327 
328**GOOD:**
329 
330```ts
331const query = ref('')
332const results = ref<string[]>([])
333 
334watch(query, async (q, _prev, onCleanup) => {
335  const controller = new AbortController()
336  onCleanup(() => controller.abort())
337 
338  const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, {
339    signal: controller.signal,
340  })
341 
342  results.value = await res.json()
343})
344```
345