v-model crea un enlace bidireccional entre los datos del padre y un componente hijo (o un elemento de formulario). En elementos nativos es azúcar sintáctico para un binding :value más un listener @input. En componentes, vincula un prop y escucha un evento de actualización.

v-model en elementos nativos

<template>
  <!-- Estas dos formas son equivalentes -->
  <input v-model="text" />
  <input
    :value="text"
    @input="text = ($event.target as HTMLInputElement).value"
  />
</template>

<script setup>
import { ref } from 'vue'
const text = ref('')
</script>

Open in Vue Playground

Distintos tipos de elementos usan diferentes pares prop/evento internamente:

Elemento	Prop vinculado	Evento
<input type="text">	value	input
<textarea>	value	input
<input type="checkbox">	checked	change
<input type="radio">	checked	change
<select>	value	change

v-model en componentes (Vue 3)

<!-- Padre -->
<CustomInput v-model="search" />

<!-- Equivalente a: -->
<CustomInput :modelValue="search" @update:modelValue="search = $event" />

Open in Vue Playground

El componente recibe un prop modelValue y emite update:modelValue:

<!-- CustomInput.vue (Vue 3.4+ con defineModel) -->
<script setup>
const model = defineModel<string>()
</script>

<template>
  <input v-model="model" />
</template>

Open in Vue Playground

Qué cambió respecto a Vue 2

En Vue 2, v-model usaba value + input y solo podías tener uno por componente. Para bindings bidireccionales adicionales, necesitabas el modificador .sync con nombres de prop distintos.

<!-- Vue 2 -->
<MyDialog v-model="isOpen" :title.sync="dialogTitle" />

<!-- Vue 2 internamente: -->
<MyDialog
  :value="isOpen"
  @input="isOpen = $event"
  :title="dialogTitle"
  @update:title="dialogTitle = $event"
/>

Open in Vue Playground

En Vue 3, .sync fue eliminado. v-model ahora admite argumentos con nombre, por lo que puedes tener múltiples bindings sin una API separada:

<!-- Vue 3 -->
<MyDialog v-model="isOpen" v-model:title="dialogTitle" />

<!-- Vue 3 internamente: -->
<MyDialog
  :modelValue="isOpen"
  @update:modelValue="isOpen = $event"
  :title="dialogTitle"
  @update:title="dialogTitle = $event"
/>

Open in Vue Playground

Resumen de la migración

Vue 2	Vue 3
v-model vincula el prop value	v-model vincula el prop modelValue
Evento: input	Evento: update:modelValue
Un v-model por componente	Múltiples v-model con args con nombre
.sync para bindings bidireccionales extra	v-model:propName con nombre
Opción model para personalizar prop/evento	No es necesaria, usa v-model:name

Modificadores de v-model

Los modificadores integrados funcionan en elementos nativos:

<input v-model.lazy="msg" />
<!-- sincroniza en change, no en input -->
<input v-model.number="age" />
<!-- convierte a número -->
<input v-model.trim="name" />
<!-- elimina espacios en blanco -->

Open in Vue Playground

Los componentes pueden definir modificadores personalizados con defineModel:

<script setup>
const [model, modifiers] =
  defineModel <
  string >
  {
    set(value) {
      if (modifiers.capitalize) {
        return value.charAt(0).toUpperCase() + value.slice(1)
      }
      return value
    }
  }
</script>

Open in Vue Playground

<!-- Padre -->
<CustomInput v-model.capitalize="text" />

Open in Vue Playground

Ver también: Usar múltiples bindings v-model · ¿Cómo funciona v-model en componentes personalizados? · ¿Cómo se crean modificadores v-model personalizados?

Referencias

• v-model en componentes - Docs de Vue.js
• defineModel - Docs de Vue.js
• Bindings de formularios - Docs de Vue.js