stack/packages/mosaic/framework/skills/vue-best-practices/reference/watcheffect-flush-post-for-refs.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Use flush post for watchEffect with Template Refs	MEDIUM	Default watchEffect runs before DOM updates, causing refs to be out of sync	gotcha	vue3 watchEffect template-refs flush dom-timing

Use flush post for watchEffect with Template Refs

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.

This timing issue is particularly confusing because the watcher runs, but the ref doesn't yet reflect the current DOM state.

Task Checklist

• Use { flush: 'post' } when watchEffect accesses template refs
• Alternatively, use watchPostEffect helper for cleaner syntax
• Still include null checks as refs can be unmounted
• Consider using watch with explicit ref watching instead

Incorrect:

<script setup>
import { ref, watchEffect } from 'vue';

const inputEl = ref(null);
const text = ref('');

// WRONG: Runs BEFORE DOM update - ref may be null or stale
watchEffect(() => {
  // On first run: inputEl.value is null (DOM not rendered yet)
  // On updates: May reference old element state
  if (inputEl.value) {
    console.log('Input value:', inputEl.value.value); // Stale!
    inputEl.value.focus();
  }
});
</script>

<template>
  <input ref="inputEl" v-model="text" />
</template>

<script setup>
import { ref, watchEffect } from 'vue';

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

// WRONG: Refs array not yet populated when this runs
watchEffect(() => {
  console.log('Number of refs:', itemRefs.value.length); // Always 0!
});
</script>

<template>
  <div v-for="item in items" :key="item" :ref="(el) => itemRefs.value.push(el)">
    {{ item }}
  </div>
</template>

Correct:

<script setup>
import { ref, watchEffect } from 'vue';

const inputEl = ref(null);
const text = ref('');

// CORRECT: flush: 'post' runs AFTER DOM update
watchEffect(
  () => {
    if (inputEl.value) {
      console.log('Input value:', inputEl.value.value); // Current!
      inputEl.value.focus();
    }
  },
  { flush: 'post' },
);
</script>

<template>
  <input ref="inputEl" v-model="text" />
</template>

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

const inputEl = ref(null);
const showInput = ref(true);

// CORRECT: watchPostEffect is shorthand for flush: 'post'
watchPostEffect(() => {
  if (inputEl.value) {
    inputEl.value.focus();
  }
});
</script>

<template>
  <input v-if="showInput" ref="inputEl" />
</template>

<script setup>
import { ref, watch, onMounted } from 'vue';

const inputEl = ref(null);

// ALTERNATIVE: Use watch on the ref directly
watch(
  inputEl,
  (el) => {
    if (el) {
      el.focus();
    }
  },
  { flush: 'post' },
);

// ALTERNATIVE: For one-time setup, onMounted is sufficient
onMounted(() => {
  inputEl.value?.focus();
});
</script>

<template>
  <input ref="inputEl" />
</template>

<script setup>
import { useTemplateRef, watchPostEffect } from 'vue';

// Vue 3.5+ with useTemplateRef
const input = useTemplateRef('my-input');

// CORRECT: watchPostEffect with useTemplateRef
watchPostEffect(() => {
  input.value?.focus();
});
</script>

<template>
  <input ref="my-input" />
</template>

Flush Options Explained

// Default: 'pre' - runs before DOM update
watchEffect(() => { ... }) // Same as { flush: 'pre' }

// 'post' - runs after DOM update (use for refs)
watchEffect(() => { ... }, { flush: 'post' })
watchPostEffect(() => { ... }) // Shorthand

// 'sync' - runs synchronously (rarely needed, can cause issues)
watchEffect(() => { ... }, { flush: 'sync' })
watchSyncEffect(() => { ... }) // Shorthand

When to Use Each Flush Mode

Scenario	Recommended Flush
Accessing template refs	post
Reading updated DOM	post
Triggering before render	pre (default)
Performance-critical sync updates	sync (with caution)

Reference

• Vue.js Watchers - Callback Flush Timing
• Vue.js watchEffect API