charging-cabinet/software/h5-uniapp/agent/skills/vue-best-practices/reference/definemodel-object-mutation-no-emit.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
defineModel Object Properties Must Be Replaced, Not Mutated	HIGH	Mutating object properties via defineModel doesn't emit update events, breaking parent sync	gotcha	vue3 v-model defineModel objects reactivity two-way-binding

defineModel Object Properties Must Be Replaced, Not Mutated

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.

This happens because Vue only detects when the model.value reference itself changes, not when properties of the object are mutated in place.

Task Checklist

• Never mutate object properties directly: model.value.prop = x
• Always create a new object reference when updating: model.value = {...model.value, prop: x}
• For arrays, use spread or slice: model.value = [...model.value, newItem]
• Consider using structuredClone for deeply nested objects

Incorrect - Mutation without event emission:

<script setup>
// Child component with object v-model
const model = defineModel<{ name: string; age: number }>()

function updateName(newName: string) {
  // WRONG: This mutates the object in place
  // Parent receives NO update:modelValue event!
  model.value.name = newName
}

function addToList() {
  // WRONG: Push mutates the array
  model.value.items.push('new item')  // Parent not notified
}
</script>

Correct - Replace object reference to trigger event:

<script setup>
const model = defineModel<{ name: string; age: number }>()

function updateName(newName: string) {
  // CORRECT: Create new object reference
  // This triggers update:modelValue event to parent
  model.value = {
    ...model.value,
    name: newName
  }
}

function addToList() {
  // CORRECT: Create new array reference
  model.value = {
    ...model.value,
    items: [...model.value.items, 'new item']
  }
}
</script>

Deep Nesting Requires Full Path Replacement

<script setup>
const model = defineModel<{
  user: {
    address: {
      city: string
    }
  }
}>()

// WRONG: Deep mutation
model.value.user.address.city = 'New York'

// CORRECT: Replace entire chain
model.value = {
  ...model.value,
  user: {
    ...model.value.user,
    address: {
      ...model.value.user.address,
      city: 'New York'
    }
  }
}

// ALTERNATIVE: Use structuredClone for complex updates
function updateCity(city: string) {
  const updated = structuredClone(model.value)
  updated.user.address.city = city
  model.value = updated  // New reference triggers event
}
</script>

Race Condition Warning with Spread Operator

When multiple updates occur rapidly, earlier changes can be lost:

<script setup>
const model = defineModel<{ a: string; b: string }>()

// CAUTION: Race condition if called in same tick
function updateBothWrong() {
  model.value = { ...model.value, a: 'new-a' }  // First update
  model.value = { ...model.value, b: 'new-b' }  // May use stale model.value!
}

// CORRECT: Batch updates into single assignment
function updateBothCorrect() {
  model.value = {
    ...model.value,
    a: 'new-a',
    b: 'new-b'
  }
}
</script>

Alternative: VueUse's useVModel with Deep Option

For complex objects, consider VueUse:

<script setup>
import { useVModel } from '@vueuse/core'

const props = defineProps<{ modelValue: { name: string } }>()
const emit = defineEmits(['update:modelValue'])

// Deep tracking with passive updates
const model = useVModel(props, 'modelValue', emit, { deep: true, passive: true })

// Now direct mutations work
model.value.name = 'New Name'  // Properly syncs with parent
</script>

Reference

• Vue.js Component v-model
• GitHub Discussion: defineModel with objects
• SIMPL Engineering: Vue defineModel Pitfalls