Confusion on and additional subtleties of v-bind.sync

[davidkhess]

This is a complex topic and I might be missing something, but....

I think the docs at https://vuejs.org/v2/guide/components-custom-events.html#sync-Modifier could use three updates:

1. There should be some mention that .sync can only be used when the expression is a proper lvalue/reference. For instance: :title.sync="title"

:title.sync="title + '!'" won't work. It will generate an error along the lines of:

SyntaxError: Left hand side of operator '=' must be a reference.

Fiddle: https://jsfiddle.net/davidkhess/vs1rxwLh/3/

2. When an object is used with v-bind, I think it would be worth mentioning that unlike normal bindings with .sync that update the referenced key on the Vue instance's data (i.e. 1. above), in this case it is only going to update that literal key on the object used in the v-bind.

At least, this is my understanding of things looking at the implementation:

vuejs/vue@3965e50

Fiddle: https://jsfiddle.net/davidkhess/vs1rxwLh/33/

3. Re: this warning:

Using v-bind.sync with a literal object, such as in v-bind.sync=”{ title: doc.title }”, will not work. If you want to include multiple, unrelated data properties in the same v-bind.sync, we recommend creating a computed property that returns an object.

I think it would help to explain why a literal object doesn't work. I believe the reason is that a literal object is not going to be reactive since it isn't attached to a Vue instance's data and therefore the param on the child component will not be updated when the object's attribute is updated. The resolution is to make sure it is reactive and a computed property will do that.

However, I think the recommended solution of a computed property creates more confusion since based on 2. above, the $emit("update:...") is going to update an attribute of the object returned by the computed property which goes against the spirit of a computed property and is not easily accessible. I think it might be more useful to recommend attaching a params object to the parent's data so that the parent component can more easily watch an attribute of the params object for changes from the child component if needed.

EDIT: I'm not able to get the computed approach to work https://jsfiddle.net/davidkhess/vs1rxwLh/22/

I think it's because an object returned from a computed is not reactive.

[chrisvfritz]

Thanks for bringing up these concerns! 🙂

1. There should be some mention that .sync can only be used when the expression is a proper lvalue/reference. For instance: :title.sync="title". :title.sync="title + '!'" won't work.

Hm, I'm torn about this one, because we do explain how the syntax sugar is expanded. In this case, title.sync="title + '!'" expands to:

:title="title + '!'"
@update:title="title + '!' = $event"

And just as Vue warned you, title + '!' on the left-hand of an assignment doesn't make any sense.

2. When an object is used with v-bind, I think it would be worth mentioning that unlike normal bindings with .sync that update the referenced key on the Vue instance's data (i.e. 1. above), in this case it is only going to update that literal key on the object used in the v-bind.

Actually, in both cases we're updating a literal key on an object, because templates work under scope of the component instance. That means @update:title="title = $event" is really doing @update:title="this.title = $event", this being the component instance object.

3. Re: this warning: [...] I think it would help to explain why a literal object doesn't work.

I don't want to get too deep in the weeds here, but I added a little more detail about the difficulty of parsing complex expressions. 🙂

EDIT: I'm not able to get the computed approach to work: jsfiddle.net/davidkhess/vs1rxwLh/22

The returned object would have to define setters for the unrelated properties it wants to update, e.g. here. But tying this back to your earlier suggestion:

I think it might be more useful to recommend attaching a params object to the parent's data so that the parent component can more easily watch an attribute of the params object for changes from the child component if needed.

We already imply that recommendation before this comment - and as I consider it more, I've never actually encountered a use case for grouping truly unrelated properties like that, so I just removed that bit.

What do you think?

[davidkhess]

On 1., I think it could be a common mistake for less experienced developers to make since arbitrary expressions are otherwise supported in v-bind. It's only when .sync is added that an lvalue is required. The error message doesn't specifically mention a possible misuse of .sync – maybe adding a mention to the error message is another option?

On 2., true enough – however this is the only use of v-bind (as far as I know) where the reference updating isn't rooted on data of the Vue instance. I think it's easy to mistake (or forget) that behavior as some unbendable rule in all situations and expect the keys on the object to represent references to keys on data.

Ah, your solution for 3. is not what I was envisioning when I read that warning. I think enhancing the language to imply the need for setters and getters on each property would help.

Yes, rereading, I see that's really the same as the usage of doc in the example. What about updating this bit:

This passes each property in the doc object (e.g. title) as an individual prop, then adds v-on update listeners for each one.

to something like

This passes each property in the doc object (e.g. title) as an individual prop, then adds v-on update listeners for each one that update each of the respective properties on the doc object.

Bottom line, from my perspective, I've been working with Vue since about 0.6 and have used this particular feature multiple times (as it came and went in support) and still have always had a hard time wrapping my head around the implications of it until I read the source code that implements it. It's one of those concepts that I think can easily get wrapped up in "magic behavior".

[davidkhess]

So, what prompted this ticket was updating some code using this feature and both not fully discerning nor liking what we've discussed above.

After wrangling with this more, I came up with this strategy as the cleanest.

1. Do use v-bind="<object>" but don't use .sync.
2. Do use a reactive object on parent's data for params. (I should note, simple usage here could be a computed without getters and setters. In my case, I need to pass the params programmatically to another component (i.e. not via a binding) so I have to rely on the object not changing and being reactive so updates to it are successfully applied to the child. A computed returns a new object when it updates so that doesn't work for me.)
3. Use a custom event to notify the parent that something has updated and it can set it directly on the params. The parent is now updated and the child component will observe the updates on the params.

I.e. the syntactic sugar of v-bind.sync="<object>" just doesn't seem to be worth the trouble once you really dig down into the weeds of an actual use case.

[chrisvfritz]

Yeah, I agree that if some people are having a problem with it, there are definitely ways we could improve our explanation for it. 🙂

To give some more background, thinking about :title.sync="title" like a normal binding with extra behavior is really the wrong way to think about it, because two-way bindings are fundamentally different. The .sync modifier works essentially like v-model, which is Vue's other syntax sugar for creating a two-way binding. The main difference is that it expands to slightly different pattern that allows you to have multiple two-way bindings on a single component, rather than being limited to just one.

Does that make sense?

Also, for the suggested rephrasing to:

This passes each property in the doc object (e.g. title) as an individual prop, then adds v-on update listeners for each one that update each of the respective properties on the doc object.

I think I could use some clarification to better understand the intent of the change. When it just ended with "for each one", what was the misunderstanding we're trying to avoid? The subject of the sentence ("each property in the doc object") hasn't changed, but it sounds like you understood "for each one" as referring to something else?

[davidkhess]

On the first, I think that's a pretty good explanation to help people understand that v-bind down is very different from .sync coming up in terms of implementation of the two behaviors. But it's not intuitive that .sync fundamentally changes the behavior of the v-bind it is being used on. If so, then shouldn't it just be a differently named directive? Something like v-bind-sync?

Maybe just focusing on how the implementation of down is very different from up is sufficient.

On the rephrasing, the issue I kept struggling with was the straightforward (but wrong) assumption that v-bind with an object is just the same thing as combining multiple individual v-binds. With that mistaken assumption, it's easy to then assume there is syntactic sugar that makes the values on the objects somehow the lvalues for the .sync instead of the object and it's key.

In reality, it's actually a pretty different mechanism and that difference is easy to overlook until you try to start using and understanding .sync in combination with it.

[peckomingo]

It seems also not possible to use v-bind and v-bind.sync on the same component. Let's say I have an object which all of its properties should two-way-bind and an object with all of its properties are normal one-way. Is there something I have overlooked or is it just not possible to use both at once?

[chrisvfritz]

@davidkhess I've just added a special note about how v-bind with the .sync modifier cannot be used with expressions, so that should improve the situation as much as we can for now.

shouldn't it just be a differently named directive? Something like v-bind-sync?

I agree that this is probably the right direction for alleviating this confusion. 🙂
We are actually thinking about moving this behavior to the v-model API for Vue 3 (e.g. v-model:prop="title" instead of v-bind:title.sync="title"), since it changes v-bind's behavior so drastically and really has more in common with v-model. That's a change we should also be able to backport to Vue 2 (while still maintaining v-bind.sync behavior so that existing apps don't break).

It seems also not possible to use v-bind and v-bind.sync on the same component.

@peckomingo That's correct, though it should be possible to fix that. A feature request issue on the vuejs/vue repo would be welcome. 🙂