1---
2name: Vue Reactivity System
3description: Core reactivity primitives - ref, reactive, computed, and watchers
4---
5 
6# Vue Reactivity System
7 
8Vue's reactivity system enables automatic tracking of state changes and DOM updates.
9 
10## ref()
11 
12Create reactive primitive values with `ref()`. Access/modify via `.value` in JavaScript, auto-unwrapped in templates.
13 
14```ts
15import { ref } from 'vue'
16 
17const count = ref(0)
18console.log(count.value) // 0
19count.value++
20```
21 
22```vue
23<script setup lang="ts">
24import { ref } from 'vue'
25 
26const count = ref(0)
27 
28function increment() {
29  count.value++
30}
31</script>
32 
33<template>
34  <button @click="increment">{{ count }}</button>
35</template>
36```
37 
38### Typing refs
39 
40```ts
41import { ref } from 'vue'
42import type { Ref } from 'vue'
43 
44// Type inference
45const year = ref(2020) // Ref<number>
46 
47// Explicit generic
48const name = ref<string | null>(null)
49 
50// Ref type annotation
51const id: Ref<string | number> = ref('abc')
52```
53 
54## reactive()
55 
56Create reactive objects. No `.value` needed, but cannot reassign the entire object.
57 
58```ts
59import { reactive } from 'vue'
60 
61interface State {
62  count: number
63  name: string
64}
65 
66const state: State = reactive({
67  count: 0,
68  name: 'Vue'
69})
70 
71state.count++ // reactive
72```
73 
74### Limitations of reactive()
75 
761. **Only works with objects** - not primitives
772. **Cannot replace entire object** - loses reactivity
783. **Destructuring loses reactivity** - use `toRefs()` instead
79 
80```ts
81const state = reactive({ count: 0 })
82 
83// ❌ Loses reactivity
84let { count } = state
85 
86// ✅ Use toRefs
87import { toRefs } from 'vue'
88const { count } = toRefs(state)
89```
90 
91## Recommendation
92 
93Use `ref()` as the primary API for declaring reactive state - it works with any value type and has consistent behavior.
94 
95## Deep Reactivity
96 
97Both `ref()` and `reactive()` are deeply reactive by default:
98 
99```ts
100const obj = ref({
101  nested: { count: 0 },
102  arr: ['foo', 'bar']
103})
104 
105// These trigger updates
106obj.value.nested.count++
107obj.value.arr.push('baz')
108```
109 
110Use `shallowRef()` or `shallowReactive()` to opt out of deep reactivity for performance.
111 
112## DOM Update Timing
113 
114DOM updates are batched and asynchronous. Use `nextTick()` to wait for updates:
115 
116```ts
117import { ref, nextTick } from 'vue'
118 
119const count = ref(0)
120 
121async function increment() {
122  count.value++
123  await nextTick()
124  // DOM is now updated
125}
126```
127 
128## Ref Unwrapping Rules
129 
130- **In templates**: Top-level refs auto-unwrap
131- **In reactive objects**: Refs auto-unwrap when accessed as properties
132- **In arrays/collections**: Refs do NOT auto-unwrap
133 
134```ts
135const count = ref(0)
136const state = reactive({ count })
137 
138console.log(state.count) // 0 (unwrapped)
139 
140const books = reactive([ref('Vue Guide')])
141console.log(books[0].value) // Need .value
142```
143 
144## computed()
145 
146Derive values from reactive state with automatic caching. Only re-evaluates when dependencies change.
147 
148```ts
149import { ref, computed } from 'vue'
150 
151const firstName = ref('John')
152const lastName = ref('Doe')
153 
154// Readonly computed
155const fullName = computed(() => `${firstName.value} ${lastName.value}`)
156 
157// Writable computed
158const fullNameWritable = computed({
159  get() {
160    return `${firstName.value} ${lastName.value}`
161  },
162  set(newValue: string) {
163    [firstName.value, lastName.value] = newValue.split(' ')
164  }
165})
166```
167 
168### Computed Best Practices
169 
170- **Getters should be pure** - no side effects, no mutating other state
171- **Don't mutate computed values** - mutate the source instead
172- **Use computed over methods** for derived data (caching benefit)
173 
174```ts
175// ✅ Cached - only recalculates when items changes
176const activeItems = computed(() => items.value.filter(x => x.active))
177 
178// ❌ Not cached - runs on every render
179function getActiveItems() {
180  return items.value.filter(x => x.active)
181}
182```
183 
184## watch()
185 
186Explicitly watch reactive sources and run side effects when they change. Lazy by default.
187 
188```ts
189import { ref, watch } from 'vue'
190 
191const id = ref(1)
192 
193watch(id, async (newId, oldId) => {
194  const data = await fetchData(newId)
195  // handle data...
196})
197```
198 
199### Watch Source Types
200 
201```ts
202const x = ref(0)
203const obj = reactive({ count: 0 })
204 
205// Single ref
206watch(x, (newX) => console.log(newX))
207 
208// Getter function
209watch(() => obj.count, (count) => console.log(count))
210 
211// Multiple sources
212watch([x, () => obj.count], ([newX, newCount]) => {
213  console.log(newX, newCount)
214})
215```
216 
217### Watch Options
218 
219```ts
220watch(source, callback, {
221  immediate: true,  // Run immediately on creation
222  deep: true,       // Watch nested properties
223  once: true,       // Trigger only once (3.4+)
224  flush: 'post'     // Run after DOM update
225})
226```
227 
228## watchEffect()
229 
230Automatically tracks dependencies and runs immediately. Re-runs when any tracked dependency changes.
231 
232```ts
233import { ref, watchEffect } from 'vue'
234 
235const todoId = ref(1)
236const data = ref(null)
237 
238watchEffect(async () => {
239  const response = await fetch(`/api/todos/${todoId.value}`)
240  data.value = await response.json()
241})
242```
243 
244### watch vs watchEffect
245 
246| Feature             | watch            | watchEffect           |
247| ------------------- | ---------------- | --------------------- |
248| Dependency tracking | Explicit         | Automatic             |
249| Lazy                | Yes              | No (immediate)        |
250| Access old value    | Yes              | No                    |
251| Best for            | Specific sources | Multiple dependencies |
252 
253## Watcher Cleanup (3.5+)
254 
255Cancel stale async operations:
256 
257```ts
258import { watch, onWatcherCleanup } from 'vue'
259 
260watch(id, async (newId) => {
261  const controller = new AbortController()
262 
263  fetch(`/api/${newId}`, { signal: controller.signal })
264 
265  onWatcherCleanup(() => controller.abort())
266})
267```
268 
269## Stopping Watchers
270 
271```ts
272const stop = watch(source, callback)
273const stop2 = watchEffect(() => { /* ... */ })
274 
275// Stop manually
276stop()
277stop2()
278 
279// Pause/Resume (3.5+)
280const { stop, pause, resume } = watchEffect(() => { /* ... */ })
281```
282 
283<!--
284Source references:
285- https://vuejs.org/guide/essentials/reactivity-fundamentals.html
286- https://vuejs.org/guide/essentials/computed.html
287- https://vuejs.org/guide/essentials/watchers.html
288- https://vuejs.org/api/reactivity-core.html
289-->
290