defineModel description in guide and API could be improved to be more precise.
Nobody has claimed this yet.
- Dominant language
- Vue
- Stars
- 3.2k
- Forks
- 5k
- Avg merge
- 14d 17h
- Merged PRs (30d)
- 1
Description
The value returned by defineModel() is a ref. It can be accessed and mutated like any other ref, except that it acts as a two-way binding between a parent value and a local one:
Its .value is synced with the value bound by the parent v-model; When it is mutated by the child, it causes the parent bound value to be updated as well.
From the Guide under the hood:
defineModel is a convenience macro. The compiler expands it to the following:
A prop named modelValue, which the local ref's value is synced with; An event named update:modelValue, which is emitted when the local ref's value is mutated.
While this is true for primitives it leads to IMO quite serious mistakes when people want to use objects or arrays as models.
I had this happen at a project i am working on where we now have quite a lot of places mutating props because developers assumed the update event is emitted when a property of the object or element of an array is updated.
I would suggest updating the text to state that the ref is a shallow ref.
In the under the hood part i would appreciate an explanation of what is actually being done under the hood ( i tried to figure it out, but could not understand the code).
I am happy to create a PR or help further flesh this out, but would appreciate some feedback first.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the linked Guide sections on basic usage and under the hood, then trace the defineModel behavior needed to explain object and array models accurately. Done means the guide precisely describes the ref behavior and gives a clearer under-the-hood explanation without implying that nested mutations emit updates.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100