agent-skills/skills/vue-best-practices/reference/watch-flush-timing.md

---
title: Use flush post When Accessing Updated DOM in Watchers
impact: MEDIUM
impactDescription: Default watcher timing runs before DOM updates, causing stale DOM reads
type: capability
tags: [vue3, watch, watchers, flush, DOM, timing, post]
---

# Use flush: 'post' When Accessing Updated DOM in Watchers

**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.

## Task Checklist

- [ ] Use `{ flush: 'post' }` when reading DOM after reactive state changes
- [ ] Use `watchPostEffect()` as a shorthand for `watchEffect` with flush: 'post'
- [ ] Avoid `{ flush: 'sync' }` unless absolutely necessary (performance impact)
- [ ] Remember default timing is ideal for most non-DOM operations

**Incorrect:**
```vue
<script setup>
import { ref, watch, watchEffect } from 'vue'

const count = ref(0)
const listItems = ref(['a', 'b', 'c'])

// BAD: DOM shows old value when this runs
watch(count, () => {
  // Element still shows the OLD count value
  const el = document.querySelector('.counter')
  console.log('DOM shows:', el.textContent)  // Old value!
})

// BAD: List DOM not yet updated
watchEffect(() => {
  console.log('Items:', listItems.value.length)
  // DOM still has old number of list items
  const items = document.querySelectorAll('.list-item')
  console.log('DOM items:', items.length)  // Old count!
})
</script>

<template>
  <div class="counter">{{ count }}</div>
  <ul>
    <li v-for="item in listItems" :key="item" class="list-item">
      {{ item }}
    </li>
  </ul>
</template>
```

**Correct:**
```vue
<script setup>
import { ref, watch, watchEffect, watchPostEffect } from 'vue'

const count = ref(0)
const listItems = ref(['a', 'b', 'c'])

// CORRECT: flush: 'post' runs after DOM update
watch(
  count,
  () => {
    const el = document.querySelector('.counter')
    console.log('DOM shows:', el.textContent)  // Correct new value!
  },
  { flush: 'post' }
)

// CORRECT: watchPostEffect shorthand
watchPostEffect(() => {
  console.log('Items:', listItems.value.length)
  const items = document.querySelectorAll('.list-item')
  console.log('DOM items:', items.length)  // Matches listItems.length!
})

// CORRECT: Using watchEffect with flush option
watchEffect(
  () => {
    // Access reactive state and DOM together
    const expectedCount = listItems.value.length
    const actualCount = document.querySelectorAll('.list-item').length
    console.log(`Expected: ${expectedCount}, Actual: ${actualCount}`)
  },
  { flush: 'post' }
)
</script>

<template>
  <div class="counter">{{ count }}</div>
  <ul>
    <li v-for="item in listItems" :key="item" class="list-item">
      {{ item }}
    </li>
  </ul>
</template>
```

## Flush Timing Options

```javascript
import { watch, watchEffect, watchPostEffect, watchSyncEffect } from 'vue'

// Default: 'pre' - runs before component DOM update
watch(source, callback)  // Same as { flush: 'pre' }

// Post: runs after component DOM update
watch(source, callback, { flush: 'post' })
watchPostEffect(callback)  // Shorthand

// Sync: runs immediately when reactive value changes
// USE WITH CAUTION - no batching, fires on every mutation
watch(source, callback, { flush: 'sync' })
watchSyncEffect(callback)  // Shorthand
```

## When to Use Each Flush Timing

| Timing | Use Case |
|--------|----------|
| `'pre'` (default) | Logic that doesn't need DOM access |
| `'post'` | Reading or measuring updated DOM |
| `'sync'` | Debug logging, simple boolean flags only |

## Sync Watcher Warning

```javascript
import { ref, watch } from 'vue'

const items = ref([1, 2, 3])

// DANGEROUS: Fires for EVERY array mutation
watch(
  items,
  () => {
    console.log('Changed!')  // Called 3 times for push, push, push
  },
  { flush: 'sync' }
)

// This triggers the watcher 3 times synchronously
items.value.push(4)
items.value.push(5)
items.value.push(6)

// Better: Use default flush which batches updates
watch(items, () => {
  console.log('Changed!')  // Called once after all mutations
}, { deep: true })
```

## Practical Example: Auto-scroll

```vue
<script setup>
import { ref, watchPostEffect } from 'vue'

const messages = ref([])
const containerRef = ref(null)

// Auto-scroll to bottom when new messages arrive
watchPostEffect(() => {
  // Access messages.value to track it
  const msgCount = messages.value.length

  // DOM is updated, safe to scroll
  if (containerRef.value && msgCount > 0) {
    containerRef.value.scrollTop = containerRef.value.scrollHeight
  }
})

function addMessage(text) {
  messages.value.push({ text, timestamp: Date.now() })
}
</script>

<template>
  <div ref="containerRef" class="messages">
    <div v-for="msg in messages" :key="msg.timestamp">
      {{ msg.text }}
    </div>
  </div>
</template>
```

## Reference
- [Vue.js Watchers - Callback Flush Timing](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing)