The peculiarity of the v-model in Vue 3 with the usual HTML elements and components of the ant-design-vue library

v-model is a directive in Vue.js, which provides two-way data binding between the model and user interface elements. This means that any changes to the user interface automatically update the values in the data model and vice versa.

How the v-model works with regular HTML elements

When you use a regular HTML element, such as <input>, with the v-model in Vue, it automatically associates the value of the text field with the searchTerm variable.

Two-way communication

v-model provides two-way binding. This means that changes in the input field update the searchTerm and vice versa.

How it is implemented

• Prop value: Vue uses the value prop to get the current value.
• Input event: Vue intercepts the input event and updates the searchTerm with the new value.

Example of work

<template>
  <div>
    <input
      v-model="searchTerm"
      placeholder="Enter the text to search for "
/>
    <p>You entered: {{ searchTerm }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue';
const searchTerm = ref('');
</script>

In this example, when you enter text in the input field, the searchTerm value is automatically updated.

Why is everything different with ant-design-vue components?

When using components from libraries such as , a slightly different syntax is required.

<a-input
  v-model:value="searchTerm"
  placeholder="Enter the text to search for"
/>

Using custom prop

The ant-design-vue components use modelValue as a prop to get the value.

Update event

Instead of the input event, update:modelValue is used to update the value.

Explicit

The v-model:value syntax adds a level of clarity, which is useful in complex components.

What is modelValue?

modelValue is the name of the prop that is used in components to get the value associated with v-model. This is the value that the components should use to transfer data.

Example of using a v-model with a

component

<a-input v-model:value="email" placeholder="Enter your email address" />

In this example, v-model:value tells Vue: "I want this component to use the prop modelValue to transfer data."

The value of the email variable will be associated with the contents of the input field (a-input), and any changes in this field will automatically update the value of email.

In the component itself, where the data is transferred, updating and data transfer back (to the parent) are carried out using $emit:

<template>
  <input
    :value="modelValue"  <!-- Here modelValue will get the value from v-model:value -->
    @input="$emit('update:modelValue', $event.target.value)" <!-- Changes are sent to the parent -->;
  />
</template>

<script setup>
import { defineProps, defineEmits } from 'vue';

// Defining the props
const props = defineProps({
  modelValue: String, <!-- Here we declare the modelValue prop --
});

// Defining events
const emit = definemits(['update:modelValue']);
</script>

When to use v-model, and when to use v-model:value?

v-model is used mainly with standard HTML elements, for example, with input fields, since they already have integrated processing logic:

<input v-model="text" />

Here, Vue automatically associates a text field (input) with the text variable.

However, when you work with library components such as ant-design-vue, you may need to use a different prop name to transfer data. In most cases, it will be modelValue:

<a-input v-model:value="searchTerm" placeholder="Enter the text to search for" />

Here v-model:value indicates that the modelValue prop should be used to bind to the searchTerm variable.

Usage example

Let's look at an example of how to use both options:

Simple input with v-model:

<template>
  <input v-model="name" placeholder="Enter your name" />
  <p>Your name: {{name }}</p>
</template>

<script setup>
import { ref } from 'vue';
const name = ref("); // Creating a reactive variable
</script>

A-input component with v-model:value:

<template>
  <a-input
    v-model:value="email"
    placeholder="Enter your email address"
/>
  <p>Your email: {{email }}</p>
</template>

<script setup>
import { ref } from 'vue';
const email = ref("); // Creating a reactive variable
</script>

Understanding when to use v-model or v-model:value helps to properly configure data binding and use library components effectively.