Component v-model ​

Starting in Vue 3.4, the recommended approach to achieve this is using the defineModel() macro:

<script setup> const model = defineModel()  function update() {  model.value++ } </script>  <template>  <div>Parent bound v-model is: {{ model }}</div>  <button @click="update">Increment</button> </template>

The parent can then bind a value with v-model:

<Child v-model="countModel" />

The value returned by defineModel() is a ref. It can be accessed and mutated like any other ref, except that it acts as a two-way binding between a parent value and a local one:

• Its .value is synced with the value bound by the parent v-model;
• When it is mutated by the child, it causes the parent bound value to be updated as well.

This means you can also bind this ref to a native input element with v-model, making it straightforward to wrap native input elements while providing the same v-model usage:

<script setup> const model = defineModel() </script>  <template>  <input v-model="model" /> </template>

Try it in the playground

Under the Hood ​

defineModel is a convenience macro. The compiler expands it to the following:

• A prop named modelValue, which the local ref's value is synced with;
• An event named update:modelValue, which is emitted when the local ref's value is mutated.

This is how you would implement the same child component shown above prior to 3.4:

<script setup> const props = defineProps(['modelValue']) const emit = defineEmits(['update:modelValue']) </script>  <template>  <input  :value="props.modelValue"  @input="emit('update:modelValue', $event.target.value)"  /> </template>

Then, v-model="foo" in the parent component will be compiled to:

<Child  :modelValue="foo"  @update:modelValue="$event => (foo = $event)" />

As you can see, it is quite a bit more verbose. However, it is helpful to understand what is happening under the hood.

Because defineModel declares a prop, you can therefore declare the underlying prop's options by passing it to defineModel:

// making the v-model required const model = defineModel({ required: true })  // providing a default value const model = defineModel({ default: 0 })

<script setup> const model = defineModel({ default: 1 }) </script>

<script setup> const myRef = ref() </script>  <template>  <Child v-model="myRef"></Child> </template>

In the child component, we can support the corresponding argument by passing a string to defineModel() as its first argument:

<script setup> const title = defineModel('title') </script>  <template>  <input type="text" v-model="title" /> </template>

Try it in the Playground

If prop options are also needed, they should be passed after the model name:

const title = defineModel('title', { required: true })

<script setup> defineProps({  title: {  required: true  } }) defineEmits(['update:title']) </script>  <template>  <input  type="text"  :value="title"  @input="$emit('update:title', $event.target.value)"  /> </template>

<script setup> const firstName = defineModel('firstName') const lastName = defineModel('lastName') </script>  <template>  <input type="text" v-model="firstName" />  <input type="text" v-model="lastName" /> </template>

Try it in the Playground

<script setup> defineProps({  firstName: String,  lastName: String })  defineEmits(['update:firstName', 'update:lastName']) </script>  <template>  <input  type="text"  :value="firstName"  @input="$emit('update:firstName', $event.target.value)"  />  <input  type="text"  :value="lastName"  @input="$emit('update:lastName', $event.target.value)"  /> </template>

Modifiers added to a component v-model can be accessed in the child component by destructuring the defineModel() return value like this:

<script setup> const [model, modifiers] = defineModel()  console.log(modifiers) // { capitalize: true } </script>  <template>  <input type="text" v-model="model" /> </template>

To conditionally adjust how the value should be read / written based on modifiers, we can pass get and set options to defineModel(). These two options receive the value on get / set of the model ref and should return a transformed value. This is how we can use the set option to implement the capitalize modifier:

<script setup> const [model, modifiers] = defineModel({  set(value) {  if (modifiers.capitalize) {  return value.charAt(0).toUpperCase() + value.slice(1)  }  return value  } }) </script>  <template>  <input type="text" v-model="model" /> </template>

Try it in the Playground

<script setup> const props = defineProps({  modelValue: String,  modelModifiers: { default: () => ({}) } })  const emit = defineEmits(['update:modelValue'])  function emitValue(e) {  let value = e.target.value  if (props.modelModifiers.capitalize) {  value = value.charAt(0).toUpperCase() + value.slice(1)  }  emit('update:modelValue', value) } </script>  <template>  <input type="text" :value="props.modelValue" @input="emitValue" /> </template>