"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)


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.


I have created a PR.

And my theory became true. :smile:


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.