v-model은 폼 입력과 상태 조각 사이에 양방향 바인딩을 만듭니다. 입력은 상태의 값을 표시하고, 입력을 편집하면 상태가 갱신됩니다 — 양방향으로 자동으로 이루어집니다.
<script setup>
import { ref } from "vue";
const name = ref("");
</script>
<template>
<input v-model="name" />
<p>You typed: {{ name }}</p> <!-- 입력하는 즉시 갱신됨 -->
</template>
내부적으로 은 바인딩과 리스너를 결합합니다.
v-model:value@input<!-- 아래 둘은 동등함 -->
<input v-model="name" />
<input :value="name" @input="name = $event.target.value" />
따라서 마법이 아니라, 바인딩-및-갱신 패턴의 편리한 단축형일 뿐입니다.
<template>
<input v-model="text" /> <!-- 텍스트 -->
<textarea v-model="message" />
<input type="checkbox" v-model="agreed" /> <!-- 불리언 -->
<input type="radio" value="a" v-model="choice" />
<select v-model="selected">...</select>
</template>
Vue는 각 컨트롤 타입에 맞는 속성/이벤트를 선택합니다(value/input, checked/change 등).
<input v-model.trim="name" /> <!-- 공백 자동 제거 -->
<input v-model.number="age" /> <!-- 숫자로 변환 -->
<input v-model.lazy="text" /> <!-- 매 키 입력 대신 `change` 시 동기화 -->
<!-- 컴포넌트는 `modelValue` prop + `update:modelValue` 이벤트로 v-model을 지원할 수 있음 -->
<CustomInput v-model="name" />
<!-- :model-value="name" @update:model-value="name = $event"와 동등 -->
이를 통해 네이티브 입력처럼 v-model과 함께 동작하는 재사용 가능한 입력 컴포넌트를 만들 수 있습니다(Vue 3는 명명된 여러 v-model도 지원합니다: v-model:title, v-model:body).
v-model은 Vue에서 폼의 초석입니다 — 양방향 데이터 흐름을 위한 수동 값 바인딩 + 이벤트 처리 보일러플레이트를 제거합니다.
:value + @input으로 분해된다는 것을 이해하면 그 원리가 명확해지고, 자신의 컴포넌트에서 v-model을 구현하는 방법을 알 수 있습니다. 수식어(.trim/.number/.lazy)는 흔한 입력 처리 요구를 선언적으로 다룹니다.