1---
2title: Use flush post for watchEffect with Template Refs
3impact: MEDIUM
4impactDescription: Default watchEffect runs before DOM updates, causing refs to be out of sync
5type: gotcha
6tags: [vue3, watchEffect, template-refs, flush, dom-timing]
7---
8 
9# Use flush post for watchEffect with Template Refs
10 
11**Impact: MEDIUM** - By default, `watchEffect` runs before the DOM is updated. When watching template refs, this means the effect may run with stale or null ref values. Use `flush: 'post'` to ensure the effect runs after DOM updates when refs are current.
12 
13This timing issue is particularly confusing because the watcher runs, but the ref doesn't yet reflect the current DOM state.
14 
15## Task Checklist
16 
17- [ ] Use `{ flush: 'post' }` when watchEffect accesses template refs
18- [ ] Alternatively, use `watchPostEffect` helper for cleaner syntax
19- [ ] Still include null checks as refs can be unmounted
20- [ ] Consider using `watch` with explicit ref watching instead
21 
22**Incorrect:**
23```vue
24<script setup>
25import { ref, watchEffect } from 'vue'
26 
27const inputEl = ref(null)
28const text = ref('')
29 
30// WRONG: Runs BEFORE DOM update - ref may be null or stale
31watchEffect(() => {
32  // On first run: inputEl.value is null (DOM not rendered yet)
33  // On updates: May reference old element state
34  if (inputEl.value) {
35    console.log('Input value:', inputEl.value.value) // Stale!
36    inputEl.value.focus()
37  }
38})
39</script>
40 
41<template>
42  <input ref="inputEl" v-model="text" />
43</template>
44```
45 
46```vue
47<script setup>
48import { ref, watchEffect } from 'vue'
49 
50const items = ref([1, 2, 3])
51const itemRefs = ref([])
52 
53// WRONG: Refs array not yet populated when this runs
54watchEffect(() => {
55  console.log('Number of refs:', itemRefs.value.length) // Always 0!
56})
57</script>
58 
59<template>
60  <div v-for="item in items" :key="item" :ref="el => itemRefs.value.push(el)">
61    {{ item }}
62  </div>
63</template>
64```
65 
66**Correct:**
67```vue
68<script setup>
69import { ref, watchEffect } from 'vue'
70 
71const inputEl = ref(null)
72const text = ref('')
73 
74// CORRECT: flush: 'post' runs AFTER DOM update
75watchEffect(() => {
76  if (inputEl.value) {
77    console.log('Input value:', inputEl.value.value) // Current!
78    inputEl.value.focus()
79  }
80}, { flush: 'post' })
81</script>
82 
83<template>
84  <input ref="inputEl" v-model="text" />
85</template>
86```
87 
88```vue
89<script setup>
90import { ref, watchPostEffect } from 'vue'
91 
92const inputEl = ref(null)
93const showInput = ref(true)
94 
95// CORRECT: watchPostEffect is shorthand for flush: 'post'
96watchPostEffect(() => {
97  if (inputEl.value) {
98    inputEl.value.focus()
99  }
100})
101</script>
102 
103<template>
104  <input v-if="showInput" ref="inputEl" />
105</template>
106```
107 
108```vue
109<script setup>
110import { ref, watch, onMounted } from 'vue'
111 
112const inputEl = ref(null)
113 
114// ALTERNATIVE: Use watch on the ref directly
115watch(inputEl, (el) => {
116  if (el) {
117    el.focus()
118  }
119}, { flush: 'post' })
120 
121// ALTERNATIVE: For one-time setup, onMounted is sufficient
122onMounted(() => {
123  inputEl.value?.focus()
124})
125</script>
126 
127<template>
128  <input ref="inputEl" />
129</template>
130```
131 
132```vue
133<script setup>
134import { useTemplateRef, watchPostEffect } from 'vue'
135 
136// Vue 3.5+ with useTemplateRef
137const input = useTemplateRef('my-input')
138 
139// CORRECT: watchPostEffect with useTemplateRef
140watchPostEffect(() => {
141  input.value?.focus()
142})
143</script>
144 
145<template>
146  <input ref="my-input" />
147</template>
148```
149 
150## Flush Options Explained
151 
152```javascript
153// Default: 'pre' - runs before DOM update
154watchEffect(() => { ... }) // Same as { flush: 'pre' }
155 
156// 'post' - runs after DOM update (use for refs)
157watchEffect(() => { ... }, { flush: 'post' })
158watchPostEffect(() => { ... }) // Shorthand
159 
160// 'sync' - runs synchronously (rarely needed, can cause issues)
161watchEffect(() => { ... }, { flush: 'sync' })
162watchSyncEffect(() => { ... }) // Shorthand
163```
164 
165## When to Use Each Flush Mode
166 
167| Scenario | Recommended Flush |
168|----------|-------------------|
169| Accessing template refs | `post` |
170| Reading updated DOM | `post` |
171| Triggering before render | `pre` (default) |
172| Performance-critical sync updates | `sync` (with caution) |
173 
174## Reference
175- [Vue.js Watchers - Callback Flush Timing](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing)
176- [Vue.js watchEffect API](https://vuejs.org/api/reactivity-core.html#watcheffect)
177