Vue watch vs watchEffect comes down to one difference: watch reacts to the sources you name, and watchEffect reacts to whatever its function happens to read. Everything else follows from that: when each one runs first, whether you get the old value, and which bugs each one makes easy. This post puts them side by side on dependency tracking, timing, deep watching and cleanup, then ends with a rule for choosing. The behavior described is Vue 3.5's, from the vuejs.org guide and API reference, and the trickier claims were checked by running them against Vue 3.5.44.
watch | watchEffect | |
|---|---|---|
| Dependencies | The source you pass: a ref, a getter, a reactive object, or an array of them | Every reactive value read while the function runs |
| First run | Only when the source changes (unless immediate: true) | Right away, synchronously |
| Old value | Yes: (value, oldValue, onCleanup) | No |
| Fires when | The source's value actually changed | Any tracked dependency changed |
| Async functions | Tracking doesn't depend on the callback | Only reads before the first await are tracked |
| Deep | Automatic for a reactive object, deep option otherwise | Tracks exactly the properties it reads |
Both return a handle that stops the watcher, both batch their runs, and both take the same flush option.
Take a search box that loads results when the query changes:
import { ref, watch, watchEffect } from 'vue'
const query = ref('')
const page = ref(1)
const results = ref<string[]>([])
watch([query, page], async ([q, p]) => {
results.value = await search(q, p)
})
watchEffect(async () => {
results.value = await search(query.value, page.value)
})Both versions reload when query or page changes. The differences:
watch doesn't run until something changes. On page load results stays empty unless you add { immediate: true }. watchEffect runs at once, which is often what you want for loading data.watch lists its dependencies. Reading the code, you know exactly what triggers it. With watchEffect, you have to read the whole function, including any function it calls.watch only fires on real changes. If the source is a getter like () => query.value.trim(), typing a space doesn't trigger a search, because the trimmed value didn't change. watchEffect re-runs whenever query changes at all.watchEffect invites: extra dependenciesBecause watchEffect tracks everything it reads, it also tracks things you didn't mean to:
watchEffect(async () => {
results.value = await search(query.value, page.value, { limit: settings.pageSize })
})If settings is reactive, changing a setting anywhere in the app now refetches the search. That might be right, or it might be a request storm you'll find in the network tab weeks later. A helper function that reads reactive state adds its reads to the effect too, and nothing in the effect's own code shows it.
The opposite bug is worse, because it fails silently. The Vue docs say it directly: watchEffect only tracks dependencies during its synchronous execution, so with an async function only the values read before the first await count.
watchEffect(async () => {
const user = await fetchUser(userId.value)
details.value = await fetchDetails(user.id, locale.value)
})userId is tracked. locale is read after an await, so it isn't. Change the language and the details stay in the old one. We ran this pattern against Vue 3.5.44: changing a ref read after the await did not re-run the effect, and changing one read before it did.
The fix is to read everything up front:
watchEffect(async () => {
const id = userId.value
const lang = locale.value
const user = await fetchUser(id)
details.value = await fetchDetails(user.id, lang)
})Or use watch([userId, locale], ...), where tracking is decided by the source and the callback can await whatever it likes.
Changing a ref doesn't run its watchers on the spot. Vue batches them: change the same ref three times in one function and the watcher runs once, with the last value. By default (flush: 'pre'), a watcher runs after the parent component has updated and before its own component's DOM updates. So inside a default watcher, the DOM still shows the old state.
flush | Runs | Shortcut for watchEffect |
|---|---|---|
'pre' (default) | Before the owner component's DOM update | watchEffect |
'post' | After the owner component's DOM update | watchPostEffect |
'sync' | Immediately on every change, no batching | watchSyncEffect |
Use 'post' when the callback measures or focuses an element that the change rendered:
watch(messages, () => {
list.value?.scrollTo({ top: list.value.scrollHeight })
}, { flush: 'post' })Avoid 'sync' unless you have a real reason. The Vue docs warn that sync watchers have no batching, so a loop that pushes items into a watched array fires the watcher on every push.
watch is shallow by default, with one exception:
const state = reactive({ user: { name: 'Ada' } })
watch(state, () => {}) // deep: fires on state.user.name = 'Grace'
watch(() => state.user, () => {}) // shallow: only fires when state.user is replaced
watch(() => state.user, () => {}, { deep: true }) // deep againPassing a reactive object directly makes the watcher deep. A getter that returns an object only fires when it returns a different object. Since Vue 3.5, deep can also be a number, the maximum depth to traverse.
Two things to know about deep watchers:
value and oldValue are the same object when the callback was triggered by a nested mutation. There's no "before" copy. If you need one, watch a getter that returns a copy or the specific fields.watchEffect, which tracks only what it reads. The Vue docs point out that this can make watchEffect cheaper than a deep watcher.When a watcher starts something async and its source changes again, the old work is stale. Register a cleanup function to cancel it. There are two ways:
import { onWatcherCleanup, watch } from 'vue'
watch(userId, (id) => {
const controller = new AbortController()
fetch(`/api/users/${id}`, { signal: controller.signal }).then(/* ... */)
onWatcherCleanup(() => controller.abort())
})
watchEffect((onCleanup) => {
const timer = setInterval(poll, 5000)
onCleanup(() => clearInterval(timer))
})The cleanup runs right before the watcher's next run, and when the watcher stops. onWatcherCleanup is new in Vue 3.5 and has a limit: it must be called synchronously, before any await. The onCleanup argument (third argument of a watch callback, first of a watchEffect function) is bound to its watcher, so it works after an await too. For a full worked example, the debounced search in the Vue composables guide uses onCleanup to clear a timer and abort the request in flight.
immediate: true runs a watch callback once at creation. The first call gets undefined as the old value.once: true (Vue 3.4+) runs the callback on the first change and then stops the watcher.pause() and resume() are on the handle in Vue 3.5. A change made while paused isn't lost: in our test, resume() ran the callback once for the change that happened during the pause.stop(), or calling the handle itself, ends the watcher for good.Watchers created synchronously in setup() or <script setup> stop when the component unmounts. A watcher created after an await or in a setTimeout isn't tied to the component, and the docs warn that you must stop it yourself to avoid a leak. Better: create it synchronously and put the condition inside it.
Here's the rule we use:
watch when the trigger matters. You need the old value, you want to react only to specific sources, the callback is async, or a reader should see at a glance what makes it run.watchEffect for synchronous effects that mirror state, where "re-run whenever anything I read changes" is exactly the intent: syncing a value to document.title, localStorage or a third-party widget.computed. It's cached, lazy and has no timing questions.The third rule catches more bugs than the other two. A watcher that keeps fullName in sync with first and last is a computed with extra steps and a window where the two disagree.
Can watchEffect give me the old value? No. Use watch, which passes (value, oldValue).
Why doesn't my watch fire when I change a property of an object? You're watching a getter or a ref that returns the object, which is shallow. Add deep: true, or watch the property itself with () => obj.prop.
Why doesn't watch(obj.count, ...) work? It passes a number, not a reactive source. Use a getter: watch(() => obj.count, ...).
Is watchEffect slower than watch? Not in general. It can be faster than a deep watch, since it only tracks the properties it reads. The cost to think about is unwanted re-runs, not tracking.
Watchers are where your app's logic lives; the screens around them don't have to be built from scratch. QuasarUI has 440 Components in 56 Blocks, from forms and tables to dashboards and pricing pages, all built with Quasar for Vue and Nuxt apps. 100 of them are Free to copy, no sign-in needed.