docs icon indicating copy to clipboard operation
docs copied to clipboard

Add a remark about watching objects/array refs

Open silentmantra opened this issue 2 years ago • 2 comments

From the docs at least for me it's not obvious that watching a ref is actually shallow watching its value only.
The problem that we know that an object/array ref makes the object/array accessed through the ref's value reactive. So intuitively it could seem that watching an object/array ref is deep like watching a reactive variable, but it's not.

I think a remark about this case should be added in the docs, otherwise I see periodically that kind of questions on the stackoverflow:

https://stackoverflow.com/questions/76786334/cannot-watch-an-array-ref-in-vue-3/76786671

silentmantra avatar Jul 28 '23 16:07 silentmantra

Absolutely. There is inconsistent terminology usage. The deep watchers section states the following:

When you call watch() directly on a reactive object, it will implicitly create a deep watcher.

At the same time, the ref() documentation section states:

ref() Takes an inner value and returns a reactive and mutable ref object.

But actually, when you call watch() on ref (which is a reactive object according to the ref() documentation), it will not create a deep watcher.

So this needs to be clarified, as the current phrasing is misleading.

alexchexes avatar Oct 28 '23 11:10 alexchexes

I was searching the documentation for a hint on why this example does not work (showing "changes: 2"). Stumbling upon the same statement in docs about watch() deeply watching by default was definitely confusing here.

soletan avatar Jun 09 '24 07:06 soletan