1---
2title: defineModel Object Properties Must Be Replaced, Not Mutated
3impact: HIGH
4impactDescription: Mutating object properties via defineModel doesn't emit update events, breaking parent sync
5type: gotcha
6tags: [vue3, v-model, defineModel, objects, reactivity, two-way-binding]
7---
8 
9# defineModel Object Properties Must Be Replaced, Not Mutated
10 
11**Impact: HIGH** - When using `defineModel()` with objects or arrays, directly mutating nested properties like `model.value.prop = x` does NOT emit the `update:modelValue` event. The parent component never receives the change notification, causing silent sync failures.
12 
13This happens because Vue only detects when the `model.value` reference itself changes, not when properties of the object are mutated in place.
14 
15## Task Checklist
16 
17- [ ] Never mutate object properties directly: `model.value.prop = x`
18- [ ] Always create a new object reference when updating: `model.value = {...model.value, prop: x}`
19- [ ] For arrays, use spread or slice: `model.value = [...model.value, newItem]`
20- [ ] Consider using structuredClone for deeply nested objects
21 
22**Incorrect - Mutation without event emission:**
23```vue
24<script setup>
25// Child component with object v-model
26const model = defineModel<{ name: string; age: number }>()
27 
28function updateName(newName: string) {
29  // WRONG: This mutates the object in place
30  // Parent receives NO update:modelValue event!
31  model.value.name = newName
32}
33 
34function addToList() {
35  // WRONG: Push mutates the array
36  model.value.items.push('new item')  // Parent not notified
37}
38</script>
39```
40 
41**Correct - Replace object reference to trigger event:**
42```vue
43<script setup>
44const model = defineModel<{ name: string; age: number }>()
45 
46function updateName(newName: string) {
47  // CORRECT: Create new object reference
48  // This triggers update:modelValue event to parent
49  model.value = {
50    ...model.value,
51    name: newName
52  }
53}
54 
55function addToList() {
56  // CORRECT: Create new array reference
57  model.value = {
58    ...model.value,
59    items: [...model.value.items, 'new item']
60  }
61}
62</script>
63```
64 
65## Deep Nesting Requires Full Path Replacement
66 
67```vue
68<script setup>
69const model = defineModel<{
70  user: {
71    address: {
72      city: string
73    }
74  }
75}>()
76 
77// WRONG: Deep mutation
78model.value.user.address.city = 'New York'
79 
80// CORRECT: Replace entire chain
81model.value = {
82  ...model.value,
83  user: {
84    ...model.value.user,
85    address: {
86      ...model.value.user.address,
87      city: 'New York'
88    }
89  }
90}
91 
92// ALTERNATIVE: Use structuredClone for complex updates
93function updateCity(city: string) {
94  const updated = structuredClone(model.value)
95  updated.user.address.city = city
96  model.value = updated  // New reference triggers event
97}
98</script>
99```
100 
101## Race Condition Warning with Spread Operator
102 
103When multiple updates occur rapidly, earlier changes can be lost:
104 
105```vue
106<script setup>
107const model = defineModel<{ a: string; b: string }>()
108 
109// CAUTION: Race condition if called in same tick
110function updateBothWrong() {
111  model.value = { ...model.value, a: 'new-a' }  // First update
112  model.value = { ...model.value, b: 'new-b' }  // May use stale model.value!
113}
114 
115// CORRECT: Batch updates into single assignment
116function updateBothCorrect() {
117  model.value = {
118    ...model.value,
119    a: 'new-a',
120    b: 'new-b'
121  }
122}
123</script>
124```
125 
126## Alternative: VueUse's useVModel with Deep Option
127 
128For complex objects, consider VueUse:
129 
130```vue
131<script setup>
132import { useVModel } from '@vueuse/core'
133 
134const props = defineProps<{ modelValue: { name: string } }>()
135const emit = defineEmits(['update:modelValue'])
136 
137// Deep tracking with passive updates
138const model = useVModel(props, 'modelValue', emit, { deep: true, passive: true })
139 
140// Now direct mutations work
141model.value.name = 'New Name'  // Properly syncs with parent
142</script>
143```
144 
145## Reference
146- [Vue.js Component v-model](https://vuejs.org/guide/components/v-model.html)
147- [GitHub Discussion: defineModel with objects](https://github.com/orgs/vuejs/discussions/10538)
148- [SIMPL Engineering: Vue defineModel Pitfalls](https://engineering.simpl.de/post/vue_definemodel/)
149