vuejs / vuejs/docs

defineModel description in guide and API could be improved to be more precise.

Open
#3,121 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Vue
Stars
3.2k
Forks
5k
Avg merge
14d 17h
Merged PRs (30d)
1

Description

From the Guide basic usage

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.