Javascript is required
ยท
2 min read

Vue Tip: Declare and Mutate v-model Props as Normal Variable Using defineModel

Vue Tip: Declare and Mutate v-model Props as Normal Variable Using defineModel Image

Info

This experimental feature will be available in Vue 3.3. If you want to try it out now in Vue 2 or Vue 3, you can use it with the Vue Macros library.

defineModel is a compiler macro that allows you to declare and mutate v-model props as the same as a normal variable.

Example without defineModel

Let's take a look at a simple example that uses v-model. We have a Parent.vue component that passes a counter ref to a Child.vue component:

Parent.vue
1<script setup lang="ts">
2import { ref } from 'vue'
3import Child from './components/Child.vue'
4
5const state = ref({ count: 0 })
6</script>
7
8<template>
9  <div>
10    <span>Parent state: {{ state }}</span>
11    <Child v-model="state.count" />
12  </div>
13</template>

Let's take a look at the implementation of the child component:

Child.vue
1<script setup lang="ts">
2import { ref } from 'vue'
3
4const props = defineProps<{ modelValue: number }>()
5
6const emit = defineEmits<{
7  (e: 'update:modelValue', value: number): void
8}>()
9
10const onClick = () => {
11  props.modelValue += 1
12  emit('update:modelValue', props.modelValue)
13}
14</script>
15
16<template>
17  <div>
18    <span>Child state: {{ modelValue }}</span>
19    <button @click="onClick">Increment child state</button>
20  </div>
21</template>

As Child.vue receives the v-model you need to declare a prop called modelValue which receives the v-model value. Additionally, you need to declare an emit called update:modelValue that is used to update the parent that the modelValue has been updated.

As props are readonly and you should not mutate them, you cannot update modelValue and will receive the following warning:

Vue warn

Set operation on key "modelValue" failed: target is readonly.

I wrote a tip about this topic and how you can solve this warning. defineModel provides a nice solution to this problem, so let's take a look at it.

Example with defineModel

Info

In the following example, I'm using Vue Macros's defineModels which behaves identically to defineModel available since Vue 3.3.0-alpha.9

We can simplify our child component by using defineModels:

Child.vue
1<script setup lang="ts">
2const { modelValue, count } = defineModels<{
3  modelValue: number
4