できない.dev

Vue 3 のカスタムコンポーネントで v-model が同期しない

v-model が同期しないときは、Vue 3.4 以降なら defineModel()、3.3 以前なら props と emits を宣言すれば直る。
v-model は :modelValue と @update:modelValue の糖衣構文である。

公開: 更新:

症状できない
node run.mjs Bad.vue
parent text = "initial", input shows ""
after typing: parent text = "initial", input shows "typed"

2026-10-09 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細

要約

Vue 3 のカスタムコンポーネントの v-model は、:modelValue と @update:modelValue に自動で展開される。
子側で props と emits が宣言されていないか、3.4+ の defineModel を旧バージョンで使うと同期しない。
Vue 3.4 以降なら defineModel()、3.3 以前なら props/emits を明示する のが基本形である。

実行例

Vue 3.5.43 を入れた node:20 のコンテナ(jsdom 上で描画)で試すと、子の内部 ref に v-model をつないだ Bad.vue は親の initial が input に届かず、入力しても親の値は initial のままだった。
defineModel を使う ModelMacro.vue と props / emits を明示した Explicit.vue は、どちらも初期値が input に入り、入力した値が親にも反映された。

$ node run.mjs Bad.vue
parent text = "initial", input shows ""
after typing: parent text = "initial", input shows "typed"
$ node run.mjs ModelMacro.vue
parent text = "initial", input shows "initial"
after typing: parent text = "typed", input shows "typed"
$ node run.mjs Explicit.vue
parent text = "initial", input shows "initial"
after typing: parent text = "typed", input shows "typed"

— 2026-10-09 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-09 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • Vue 3.5.43

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. Vue 3.4+ で defineModel を使う

<script setup lang="ts">
const model = defineModel<string>();
</script>
 
<template>
  <input v-model="model" />
</template>
<MyInput v-model="text" />

defineModel<string>() の戻り値は ref である。
v-model でそのまま接続でき、値の取得・更新・親への emit を Vue がまとめて処理する。
詳しくは Component v-model(新しいタブで開く) に載っている。

2. Vue 3.3 以前は props/emits を明示

<script setup lang="ts">
const props = defineProps<{ modelValue: string }>();
const emit = defineEmits<{
  (e: "update:modelValue", value: string): void;
}>();
</script>
 
<template>
  <input
    :value="props.modelValue"
    @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
  />
</template>

3. 名前付き v-model の名前を揃える

<UserForm
  v-model:first-name="form.firstName"
  v-model:last-name="form.lastName"
/>
<script setup lang="ts">
const firstName = defineModel<string>("firstName");
const lastName = defineModel<string>("lastName");
</script>

親側のケバブケース v-model:first-name は子の defineModel<string>('firstName') に対応する。
引数名と親の名前を一致させる。

4. 内部 ref に逃さない

子コンポーネント内で const local = ref(props.modelValue) と内部状態を作ってしまうと、親と同期しなくなる。
defineModel を使うか、props を直接 :value バインドし @input で emit する。

よくある原因

  1. prop / emit を宣言していない。
    子で defineProps / defineEmits を書かないと、親からの値も親への変更通知も成立しない。
  2. defineModel を対応前のバージョンで使っている。
    defineModel が安定したのは Vue 3.4 である。
    3.3 以前で書くとコンパイル時に展開されず、実行時に undefined を弄ることになる。
  3. 名前付き v-model の名前がずれている。
    v-model:title と書いたら、子も defineModel<string>('title') か props.title で受ける。
  4. 子が内部 ref に直結している。
    子で <input v-model="localRef" /> のように内部状態に繋ぎ、親への emit が無い。
    これで子→親も途切れるのは、子の根要素が div などのときである。
    根要素が <input> 1 個だと、宣言していない onUpdate:modelValue が属性の継承でその input に渡り、子→親だけは同期してしまう(親→子は届かない。
    Vue 3.5.43 で確認)。