Watchers | Vue.js

Creating an Application
Reactivity Fundamentals
Class and Style Bindings
Conditional Rendering
Fallthrough Attributes
Single-File Components
Server-Side Rendering (SSR)
Production Deployment
TS with Composition API
Render Functions & JSX
Vue and Web Components
Animation Techniques
Computed properties allow us to declaratively compute derived values. However, there are cases where we need to perform "side effects" in reaction to state changes - for example, mutating the DOM, or changing another piece of state based on the result of an async operation.
With the Options API, we can use the watch option to trigger a function whenever a reactive property changes:
Try it in the Playground
The watch option also supports a dot-delimited path as the key:
With Composition API, we can use the watch function to trigger a callback whenever a piece of reactive state changes:
Try it in the Playground
watch's first argument can be different types of reactive "sources": it can be a ref (including computed refs), a reactive object, a getter function, or an array of multiple sources:
Do note that you can't watch a property of a reactive object like this:
Instead, use a getter:
watch is shallow by default: the callback will only trigger when the watched property has been assigned a new value - it won't trigger on nested property changes. If you want the callback to fire on all nested mutations, you need to use a deep watcher:
When you call watch() directly on a reactive object, it will implicitly create a deep watcher - the callback will be triggered on all nested mutations:
This should be differentiated with a getter that returns a reactive object - in the latter case, the callback will only fire if the getter returns a different object:
You can, however, force the second case into a deep watcher by explicitly using the deep option:
In Vue 3.5+, the deep option can also be a number indicating the max traversal depth - i.e. how many levels should Vue traverse an object's nested properties.
Deep watch requires traversing all nested properties in the watched object, and can be expensive when used on large data structures. Use it only when necessary and beware of the performance implications.
watch is lazy by default: the callback won't be called until the watched source has changed. But in some cases we may want the same callback logic to be run eagerly - for example, we may want to fetch some initial data, and then re-fetch the data whenever relevant state changes.
We can force a watcher's callback to be executed immediately by declaring it using an object with a handler function and the immediate: true option:
The initial execution of the handler function will happen just before the created hook. Vue will have already processed the data, computed, and methods options, so those properties will be available on the first invocation.
We can force a watcher's callback to be executed immediately by passing the immediate: true option:
Watcher's callback will execute whenever the watched source changes. If you want the callback to trigger only once when the source changes, use the once: true option.
It is common for the watcher callback to use exactly the same reactive state as the source. For example, consider the following code, which uses a watcher to load a remote resource whenever the todoId ref changes:
In particular, notice how the watcher uses todoId twice, once as the source and then again inside the callback.
This can be simplified with watchEffect(). watchEffect() allows us to track the callback's reactive dependencies automatically. The watcher above can be rewritten as:
Here, the callback will run immediately, there's no need to specify immediate: true. During its execution, it will automatically track todoId.value as a dependency (similar to computed properties). Whenever todoId.value changes, the callback will be run again. With watchEffect(), we no longer need to pass todoId explicitly as the source value.
You can check out this example of watchEffect() and reactive data-fetching in action.
For examples like these, with only one dependency, the benefit of watchEffect() is relatively small. But for watchers that have multiple dependencies, using watchEffect() removes the burden of having to maintain the list of dependencies manually. In addition, if you need to watch several properties in a nested data structure, watchEffect() may prove more efficient than a deep watcher, as it will only track the properties that are used in the callback, rather than recursively tracking all of them.
watchEffect only tracks dependencies during its synchronous execution. When using it with an async callback, only properties accessed before the first await tick will be tracked.
watch and watchEffect both allow us to reactively perform side effects. Their main difference is the way they track their reactive dependencies: