1---
2title: Use flush post When Accessing Updated DOM in Watchers
3impact: MEDIUM
4impactDescription: Default watcher timing runs before DOM updates, causing stale DOM reads
5type: capability
6tags: [vue3, watch, watchers, flush, DOM, timing, post]
7---
8 
9# Use flush: 'post' When Accessing Updated DOM in Watchers
10 
11**Impact: MEDIUM** - By default, watcher callbacks run before the component's DOM is updated. If you access the DOM in a watcher callback, you'll see the pre-update state. Use `flush: 'post'` or `watchPostEffect` when you need to access the updated DOM.
12 
13## Task Checklist
14 
15- [ ] Use `{ flush: 'post' }` when reading DOM after reactive state changes
16- [ ] Use `watchPostEffect()` as a shorthand for `watchEffect` with flush: 'post'
17- [ ] Avoid `{ flush: 'sync' }` unless absolutely necessary (performance impact)
18- [ ] Remember default timing is ideal for most non-DOM operations
19 
20**Incorrect:**
21```vue
22<script setup>
23import { ref, watch, watchEffect } from 'vue'
24 
25const count = ref(0)
26const listItems = ref(['a', 'b', 'c'])
27 
28// BAD: DOM shows old value when this runs
29watch(count, () => {
30  // Element still shows the OLD count value
31  const el = document.querySelector('.counter')
32  console.log('DOM shows:', el.textContent)  // Old value!
33})
34 
35// BAD: List DOM not yet updated
36watchEffect(() => {
37  console.log('Items:', listItems.value.length)
38  // DOM still has old number of list items
39  const items = document.querySelectorAll('.list-item')
40  console.log('DOM items:', items.length)  // Old count!
41})
42</script>
43 
44<template>
45  <div class="counter">{{ count }}</div>
46  <ul>
47    <li v-for="item in listItems" :key="item" class="list-item">
48      {{ item }}
49    </li>
50  </ul>
51</template>
52```
53 
54**Correct:**
55```vue
56<script setup>
57import { ref, watch, watchEffect, watchPostEffect } from 'vue'
58 
59const count = ref(0)
60const listItems = ref(['a', 'b', 'c'])
61 
62// CORRECT: flush: 'post' runs after DOM update
63watch(
64  count,
65  () => {
66    const el = document.querySelector('.counter')
67    console.log('DOM shows:', el.textContent)  // Correct new value!
68  },
69  { flush: 'post' }
70)
71 
72// CORRECT: watchPostEffect shorthand
73watchPostEffect(() => {
74  console.log('Items:', listItems.value.length)
75  const items = document.querySelectorAll('.list-item')
76  console.log('DOM items:', items.length)  // Matches listItems.length!
77})
78 
79// CORRECT: Using watchEffect with flush option
80watchEffect(
81  () => {
82    // Access reactive state and DOM together
83    const expectedCount = listItems.value.length
84    const actualCount = document.querySelectorAll('.list-item').length
85    console.log(`Expected: ${expectedCount}, Actual: ${actualCount}`)
86  },
87  { flush: 'post' }
88)
89</script>
90 
91<template>
92  <div class="counter">{{ count }}</div>
93  <ul>
94    <li v-for="item in listItems" :key="item" class="list-item">
95      {{ item }}
96    </li>
97  </ul>
98</template>
99```
100 
101## Flush Timing Options
102 
103```javascript
104import { watch, watchEffect, watchPostEffect, watchSyncEffect } from 'vue'
105 
106// Default: 'pre' - runs before component DOM update
107watch(source, callback)  // Same as { flush: 'pre' }
108 
109// Post: runs after component DOM update
110watch(source, callback, { flush: 'post' })
111watchPostEffect(callback)  // Shorthand
112 
113// Sync: runs immediately when reactive value changes
114// USE WITH CAUTION - no batching, fires on every mutation
115watch(source, callback, { flush: 'sync' })
116watchSyncEffect(callback)  // Shorthand
117```
118 
119## When to Use Each Flush Timing
120 
121| Timing | Use Case |
122|--------|----------|
123| `'pre'` (default) | Logic that doesn't need DOM access |
124| `'post'` | Reading or measuring updated DOM |
125| `'sync'` | Debug logging, simple boolean flags only |
126 
127## Sync Watcher Warning
128 
129```javascript
130import { ref, watch } from 'vue'
131 
132const items = ref([1, 2, 3])
133 
134// DANGEROUS: Fires for EVERY array mutation
135watch(
136  items,
137  () => {
138    console.log('Changed!')  // Called 3 times for push, push, push
139  },
140  { flush: 'sync' }
141)
142 
143// This triggers the watcher 3 times synchronously
144items.value.push(4)
145items.value.push(5)
146items.value.push(6)
147 
148// Better: Use default flush which batches updates
149watch(items, () => {
150  console.log('Changed!')  // Called once after all mutations
151}, { deep: true })
152```
153 
154## Practical Example: Auto-scroll
155 
156```vue
157<script setup>
158import { ref, watchPostEffect } from 'vue'
159 
160const messages = ref([])
161const containerRef = ref(null)
162 
163// Auto-scroll to bottom when new messages arrive
164watchPostEffect(() => {
165  // Access messages.value to track it
166  const msgCount = messages.value.length
167 
168  // DOM is updated, safe to scroll
169  if (containerRef.value && msgCount > 0) {
170    containerRef.value.scrollTop = containerRef.value.scrollHeight
171  }
172})
173 
174function addMessage(text) {
175  messages.value.push({ text, timestamp: Date.now() })
176}
177</script>
178 
179<template>
180  <div ref="containerRef" class="messages">
181    <div v-for="msg in messages" :key="msg.timestamp">
182      {{ msg.text }}
183    </div>
184  </div>
185</template>
186```
187 
188## Reference
189- [Vue.js Watchers - Callback Flush Timing](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing)
190