Beginner feedback for the devs. Composition API syntax inconsistency: I would prefer to use '.value' properties in templates too

[NSNS33]

As the title suggests I would actually prefer to use '.value' properties in templates too as that would unify the syntax between the script section and the template section in the code.

Reading the official docs at first I actually got the impression that omitting the '.value' in the template section with Composition API was optional (see the quote below*). Now I know that wasn't the case and we simply cannot use .value syntax in the template section. The docs say that the automatic unwrapping of refs in templates is a convenience feature. I beg to differ. I think it causes unnecessary inconsistency in the syntax and makes it more difficult for beginners to learn it (I am a beginner in Vue).

I would also propose to change the wording in the docs so that the reader immediately understands that using .value in the template section is explicitly prohibited. The wording should be something like "You can not use .value when using refs in the template.".

*The quote:

"Notice that we did not need to append .value when using the ref in the template. For convenience, refs are automatically unwrapped when used inside templates (with a few caveats)."

[kaikaibenkai]

+1 from https://stackoverflow.com/q/77600199/19171888

Perhaps a compiler option could be added to control this behavior
Or... Vue Macros?

[jacekkarczmarczyk]

I would also propose to change the wording in the docs so that the reader immediately understands that using .value in the template section is explicitly prohibited. The wording should be something like "You can not use .value when using refs in the template.".

It's not prohibited

<template>{{ foo.ref.value }}</template>

<script setup>
const foo = {
  ref: ref('blah')
}
</script>

[darrylnoakes]

I would also propose to change the wording in the docs so that the reader immediately understands that using .value in the template section is explicitly prohibited. The wording should be something like "You can not use .value when using refs in the template.".

It's not prohibited. Top-level refs are unwrapped, meaning any refs that are at component/module scope acts as if you had included .value already. The key is the "top-level": a ref inside an object, etc., will not be unwrapped.

---

Personally, I find the unwrapping makes things very succinct most of the time, but anything slightly complex gets confusing as you have to keep the unwrapping in mind.

In one way, this is good: as a rule of thumb, if your code is confusing you're probably going about it the wrong way. However, this applies to any nested object, so even <div v-if="message.doShow.value"> gets dragged in here.

Unfortunately, there are so many edge cases and considerations.
As an example, say I suggest making any "simple expression" having unwrapping for convenience, and everything else requires .value as usual. But what gets included in "simple" then?
Is message.state === "hidden" simple? Or do I have to use message.state.value === "hidden"?
I would want <div v-if="message.doShow"> to be auto-unwrapped. But what if I was actually non-reactively checking that the property was set? So even that wouldn't be an easy case.
It needs to work for most cases, and also be simple and understandable.

And so we come the full circle: unwrap top level refs, as that is what you usually are working with.

---

If you have a situation where it would make things simpler, there is a workaround. You can use reactive objects instead of objects of refs, as reactive objects do not use .value.
If you have the object of refs from an external source, or are using it for something else, you can convert it / create a copy by passing it through reactive; the result will be a linked reactive object.
In some cases, you can use a single ref with an object value.

[NSNS33]

All very good and very insightful and interesting replies in the thread. Thank you very much, guys!

Now, excuse my ignorance/naivety but why is it necessary to have autounwrap at all if it causes so many exceptions in the syntax? I would much rather have no autounwrap whatsoever and have a consistent syntax instead. It's much easier to remember adding .value after any reactive item in the code, no matter the place in the code, than to remember all the rules connected to the autounwrap. It is currently day 3 of my really intensive (6-7 hours a day) studying of how reactivity in Vue works and I feel like it's not really justified. I simply don't see the value in autounwrap at all. Somewhat shorter code? Not enough in my opinion considering the tradeoff. But as I said I am a beginner in Vue so excuse me if I miss more important context connected to the wrapping logic.

Feel free to put me in my place. I thank you very much for your time and know-how.

[darrylnoakes]

Just generally, you usually will only use refs that will be unwrapped.

E.g.:

<div v-if="doShowMessage">{{ message }}</div>
<!-- vs -->
<div v-if="doShowMessage.value">{{ message.value }}</div>

<li v-for="message in messages">{{ message }}</li>
<!-- vs -->
<li v-for="message in messages.value">{{ message }}</li>

---

I do agree that it can be confusing, but it is a rather nice feature once you get your head around it.

An option to disable auto-unwrapping would be nice, but the risk of fragmentation is too great. Code would not be interoperable and changes between styles would be time consuming and error prone.

Maybe it can change in Vue 4...

[kaikaibenkai]

I personally think this feature is to be compatible with Vue 2.