Simpler Two-Way Binding in Vue With defineModel

v-model is a powerful feature in Vue that allows you to create two-way data bindings on your components. However, defining the props and emits in every component can be a bit verbose.

In this article, I'll show you how to simplify two-way binding in Vue with the defineModel compiler-macro, which is now the recommended way to define v-model bindings in Vue 3.4 and later.

The "Problem"

When you create a component that uses v-model, you need to define a prop and an emit for the value. For example, if you have a component that uses v-model to bind to a value prop, you would need to define the following:

1<script setup lang="ts">
2  const props = defineProps(['modelValue'])
3  const emit = defineEmits(['update:modelValue'])
4</script>
5
6<template>
7  <input
8    :value="modelValue"
9    @input="emit('update:modelValue', $event.target.value)"
10  />
11</template>

The Solution

defineModel is a new <script setup> macro that aims to simplify the implementation of components that support v-model. It automatically defines the modelValue prop and the update:modelValue emit for you.

Let's rewrite the above example using defineModel:

1<script setup lang="ts">
2const model = defineModel()
3</script>
4
5<template>
6  <input v-model="model">
7</template>

I love this simple and clean syntax. It makes the code much easier to read and write.

defineModel() returns a ref, which is automatically bound to the modelValue prop and emits the update:modelValue event when the value changes. The .value is synced with the value bound by the parent v-model. When the ref is updated, the value bound by the parent is automatically updated.

This allows us to use v-model directly on the native input element without additional code.

Options

defineModel also accepts an optional options object to configure the behavior of the model:

1<script setup lang="ts">
2// making the v-model required
3const model = defineModel({ required: true })
4
5// providing a default value
6const model = defineModel({ default: 0 })
7</script>

Multiple v-model bindings

If you have multiple v-model bindings in your component, you can use defineModels to define multiple models at once:

1<template>
2  <Child
3    v-model:first-name="firstName"
4    v-model:last-name="lastName"
5  />
6</template>

1<script setup lang="ts">
2const firstName = defineModel('firstName')
3const lastName = defineModel('lastName')
4</script>
5
6<template>
7  <input v-model="firstName" />
8  <input v-model="lastName" />
9</template>

If prop options are also needed, you can pass them after the model name:

1<script setup lang="ts">
2const firstName = defineModel('firstName', { required: true })
3const lastName = defineModel('lastName', { default: '-' })
4</script>
5
6<template>
7  <input v-model="firstName" />
8  <input v-model="lastName" />
9</template>

Modifiers

defineModel also supports modifiers. You can use modifiers to customize the behavior of the model. Let's take a look at a simple modifier that modifies every character of the model value and makes it uppercase:

1<template>
2  <Child v-model.uppercase="message" />
3</template>

1<script setup lang="ts">
2const [model, modifiers] = defineModel({
3  set(value) {
4    if (modifiers.capitalize) {
5      return value.toUpperCase()
6    }
7    return value
8  }
9})
10</script>
11
12<template>
13  <input v-model="model" />
14</template>

Typing

You can define the type of the model value inside the options object:

1<script setup lang="ts">
2const count = defineModel({
3  type: Number,
4  default: 0
5})
6</script>

If you are using TypeScript, you can also define the type of the model value and modifiers in the following way:

1<script setup lang="ts">
2const modelValue = defineModel<string>()
3//    ^? Ref<string | undefined>
4
5// default model with options, required removes possible undefined values
6const modelValue = defineModel<string>({ required: true })
7//    ^? Ref<string>
8
9const [modelValue, modifiers] = defineModel<string, 'trim' | 'uppercase'>()
10//                 ^? Record<'trim' | 'uppercase', true | undefined>
11</script>

StackBlitz

Try it yourself in the following StackBlitz project:

Conclusion

I love the new defineModel compiler macro. It makes two-way binding in Vue much simpler and cleaner. I hope you find this feature as helpful as I do.

If you liked this article, follow me on X to get notified about my new blog posts and more content.

Alternatively (or additionally), you can subscribe to my weekly Vue & Nuxt newsletter: