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 thesearchTerm
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.
Using the v-model
with regular HTML elements is simple and intuitive. With components from libraries, a more explicit indication is required, which leads to the need to use v-model:value
.