Skip to content

Commit 74ed547

Browse files
committed
Reword the section on watchEffect
1 parent 5cc6d7a commit 74ed547

File tree

1 file changed

+18
-15
lines changed

1 file changed

+18
-15
lines changed

src/guide/essentials/watchers.md

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ The initial execution of the handler function will happen just before the `creat
253253
We can force a watcher's callback to be executed immediately by passing the `immediate: true` option:
254254

255255
```js
256-
watch(obj, (newValue, oldValue) => {
256+
watch(source, (newValue, oldValue) => {
257257
// ...
258258
}, { immediate: true })
259259
```
@@ -264,35 +264,38 @@ watch(obj, (newValue, oldValue) => {
264264

265265
## `watchEffect()` \*\* {#watcheffect}
266266

267-
`watch()` is lazy: 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 may find ourselves doing this:
267+
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:
268268

269269
```js
270-
const url = ref('https://...')
270+
const todoId = ref(1)
271271
const data = ref(null)
272272

273-
async function fetchData() {
274-
const response = await fetch(url.value)
273+
watch(todoId, async () => {
274+
const response = await fetch(
275+
`https://jsonplaceholder.typicode.com/todos/${todoId.value}`
276+
)
275277
data.value = await response.json()
276-
}
277-
278-
// fetch immediately
279-
fetchData()
280-
// ...then watch for url change
281-
watch(url, fetchData)
278+
}, { immediate: true })
282279
```
283280

284-
This can be simplified with [`watchEffect()`](/api/reactivity-core.html#watcheffect). `watchEffect()` allows us to perform a side effect immediately while automatically tracking the effect's reactive dependencies. The above example can be rewritten as:
281+
In particular, notice how the watcher uses `todoId` twice, once as the source and then again inside the callback.
282+
283+
This can be simplified with [`watchEffect()`](/api/reactivity-core.html#watcheffect). `watchEffect()` allows us to track the callback's reactive dependencies automatically. The watcher above can be rewritten as:
285284

286285
```js
287286
watchEffect(async () => {
288-
const response = await fetch(url.value)
287+
const response = await fetch(
288+
`https://jsonplaceholder.typicode.com/todos/${todoId.value}`
289+
)
289290
data.value = await response.json()
290291
})
291292
```
292293

293-
Here, the callback will run immediately. During its execution, it will also automatically track `url.value` as a dependency (similar to computed properties). Whenever `url.value` changes, the callback will be run again.
294+
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.
295+
296+
You can check out [this example](/examples/#fetching-data) of `watchEffect()` and reactive data-fetching in action.
294297

295-
You can check out [this example](/examples/#fetching-data) with `watchEffect` and reactive data-fetching in action.
298+
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.
296299

297300
:::tip
298301
`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.

0 commit comments

Comments
 (0)