Skip to content

docs(v-model): document factory-function defaults for objects/arrays#3434

Open
pcoterecollective wants to merge 1 commit into
vuejs:mainfrom
pcoterecollective:docs-v-model-non-primitive-defaults
Open

docs(v-model): document factory-function defaults for objects/arrays#3434
pcoterecollective wants to merge 1 commit into
vuejs:mainfrom
pcoterecollective:docs-v-model-non-primitive-defaults

Conversation

@pcoterecollective

@pcoterecollective pcoterecollective commented Jul 21, 2026

Copy link
Copy Markdown

What

The defineModel() default section on the v-model page only documents a primitive default (default: 0). Because defineModel() declares a regular prop, its default is resolved through the same machinery as defineProps — so an object/array default that isn't a factory function is shared across every component instance, and mutating the model in one instance leaks into the others.

This adds a short note + example right after the existing default example, and links to Prop Validation where the factory-function rule is already stated. The page even uses factory syntax for modelModifiers, just never for the value default.

Repro

Vue SFC Playground

  • Object-literal default (default: {}): both instances render the same object id — one shared reference.
  • Factory default (default: () => ({})): each instance renders a different object id — a fresh object per instance.

@netlify

netlify Bot commented Jul 21, 2026

Copy link
Copy Markdown

Deploy Preview for vuejs ready!

Name Link
🔨 Latest commit 6410dc0
🔍 Latest deploy log https://app.netlify.com/projects/vuejs/deploys/6a5f8d2fdd9f0a0008b2a86d
😎 Deploy Preview https://deploy-preview-3434--vuejs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@pcoterecollective

Copy link
Copy Markdown
Author

@brc-dd — mind a quick look when you get a chance? The v-model page only documents a primitive defineModel() default (default: 0), so object/array defaults and the factory-function requirement aren't covered. Repro + playground link are in the description.

@brc-dd

brc-dd commented Jul 23, 2026

Copy link
Copy Markdown
Member

I'm fine with adding it, but generally speaking you should never mutate a prop or model. The recommended way is to create a model and do an assignment to replace the value.

@brc-dd
brc-dd requested a review from bencodezen July 23, 2026 02:50
@whysopaul

Copy link
Copy Markdown
Contributor

Just a quick note: a pull request with a similar proposal has already been opened (#3410)

const model = defineModel({ default: 0 })
```

When the default value is an object or array, return it from a factory function, just as with [prop defaults](/guide/components/props#prop-validation). Otherwise every component instance that falls back to the default shares the **same** reference, and mutating the model in one instance leaks into the others:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When the default value is an object or array, return it from a factory function, just as with [prop defaults](/guide/components/props#prop-validation). Otherwise every component instance that falls back to the default shares the **same** reference, and mutating the model in one instance leaks into the others:
When the default value is an object or array, it will be shared across all instances of the component because it shares the same reference. In other words, changing the model in one instance will affect the other instances.
Similar to [prop defaults](/guide/components/props#prop-validation), if you want the component instances to have their own unique values, you need to return it from a factory function.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants