"props" reactivity in the documentation

I would like to create this thread to discuss an extension of the documentation that details how and when props are reactive. Take this thread as a starting point: Update data when prop changes. Data derived from prop - I feel there is a lot of confusion about props and reactivity. I would propose that the following should be mentioned in the vue docs:

Whether props actually are reactive depends on several factors:

  • primitive props (String, Number, … ) can be reactive in a component only if made dynamic via v-bind:
    • they are reactive if used in computed properties or in methods
    • they are not reactive if used in data as initial value - unless being referenced by a watch function. Also note that when used as non-reactive initial data the assigned value will be the props value at the moment of component creation*.
  • Object (or Array) props can be reactive whether or not passed via v-bind if the object itself is being passed and stored in data - and not just primitive values of the object.
    • If the Object reference is stored in data any use of this data will be reactive towards the props value
    • If the Object is cloned or only primitives are stored in data the same rules apply as for primitive props above

*: Note that the “moment of creation” depends on many factors of how you define and use a component: v-if vs v-show, using keep-alive vs not using it or when single file components are loaded.

_
Are my points correct?
How to best phrase this and should code examples be added?
Where to put this in the docs? (proposal: below https://vuejs.org/v2/guide/components.html#Dynamic-Props with a new heading)

2 Likes

This is an excellent suggestion and something that really should be clarified in it’s own section in the official documentation.

Ideally it should be explained right after https://vuejs.org/v2/guide/components.html#Passing-Data-with-Props section

Thanks for your feedback! I have checked the passage you linked, but I feel there is a problem with putting my proposed content right after “Passing data with props”: the passage “Dynamic Props” follows further down and is required knowledge for understanding my points. Thus I feel it should come after “Dynamic Props”.

What do you think? Anybody confirming the validity of my points?

I will create a pull request soon if I get no further comments.

You might get a better and faster answer, if you create a PR here.

Scott

I have created a PR.

And my theory became true. :smile:

Scott

Undesired “reactivity” can be very tricky to debug and understand, especially if you are a newcomer. I’ve raised another similar case here which occurs when passing objects to parent component in an $emit call. I wonder if it could be worth updating the event section too, maybe with some warnings.