Basic usage

You can create two-way data bindings on form , and elements using the v-model directive. It automatically picks the correct method to update the element based on the control type. Although somewhat magical, v-model is essentially syntactic sugar. It is responsible for listening to user input events to update data, and does some special processing for some extreme scenarios.
v-model ignores the initial values ​​of the value, checked, and selected attribute s of all form elements and always uses the Vue instance data as the data source. You should declare the initial value in the component's data option via JavaScript.
v-model internally uses different properties and throws different events for different input elements:

• text and textarea elements use the value property and input event;
• checkbox and radio use checked property and change event;
• The select field has value as prop and change as event.

text

<input v-model="message" placeholder="edit me">
<p>Message is: {{ message }}</p>

multiline text

<span>Multiline message is:</span>
<p style="white-space: pre-line;">{{ message }}</p>
<br>
<textarea v-model="message" placeholder="add multiple lines"></textarea>

checkbox

A single checkbox, bound to a boolean:

<input type="checkbox" id="checkbox" v-model="checked">
<label for="checkbox">{{ checked }}</label>

Multiple checkboxes, bound to the same array:

<input type="checkbox" id="jack" value="Jack" v-model="checkedNames">
<label for="jack">Jack</label>
<input type="checkbox" id="john" value="John" v-model="checkedNames">
<label for="john">John</label>
<input type="checkbox" id="mike" value="Mike" v-model="checkedNames">
<label for="mike">Mike</label>
<br>
<span>Checked names: {{ checkedNames }}</span>

new Vue({
  el: '...',
  data: {
    checkedNames: []
  }
})

single button

<div id="example-4">
  <input type="radio" id="one" value="One" v-model="picked">
  <label for="one">One</label>
  <br>
  <input type="radio" id="two" value="Two" v-model="picked">
  <label for="two">Two</label>
  <br>
  <span>Picked: {{ picked }}</span>
</div>

new Vue({
  el: '#example-4',
  data: {
    picked: ''
  }
})

selection box

single choice

<div id="example-5">
  <select v-model="selected">
    <option disabled value="">please choose</option>
    <option>A</option>
    <option>B</option>
    <option>C</option>
  </select>
  <span>Selected: {{ selected }}</span>
</div>

new Vue({
  el: '...',
  data: {
    selected: ''
  }
})

If the initial value of the v-model expression fails to match any of the options, the element will be rendered in an "unselected" state. In iOS, this prevents the user from selecting the first option. Because in this case, iOS will not trigger the change event. Therefore, it is more recommended to provide a disable option with an empty value as above.

Multiple choice

<div id="example-6">
  <select v-model="selected" multiple style="width: 50px;">
    <option>A</option>
    <option>B</option>
    <option>C</option>
  </select>
  <br>
  <span>Selected: {{ selected }}</span>
</div>

new Vue({
  el: '#example-6',
  data: {
    selected: []
  }
})

Dynamic options for rendering with v-for

<select v-model="selected">
  <option v-for="option in options" v-bind:value="option.value">
    {{ option.text }}
  </option>
</select>
<span>Selected: {{ selected }}</span>

new Vue({
  el: '...',
  data: {
    selected: 'A',
    options: [
      { text: 'One', value: 'A' },
      { text: 'Two', value: 'B' },
      { text: 'Three', value: 'C' }
    ]
  }
})

value binding

For radio button, checkbox and select box options, the value bound by v-model is usually a static string (or a boolean value for checkboxes):

<!-- When selected,`picked` as string "a" -->
<input type="radio" v-model="picked" value="a">

<!-- `toggle` for true or false -->
<input type="checkbox" v-model="toggle">

<!-- When the first option is selected,`selected` as string "abc" -->
<select v-model="selected">
  <option value="abc">ABC</option>
</select>

But sometimes we may want to bind the value to a dynamic property of the Vue instance, which can be achieved with v-bind, and the value of this property may not be a string.

checkbox

<input
  type="checkbox"
  v-model="toggle"
  true-value="yes"
  false-value="no"
>

// when selected
vm.toggle === 'yes'
// when not selected
vm.toggle === 'no'

The true-value and false-value attribute s here do not affect the value attribute of the input control, because the browser does not include unchecked checkboxes when submitting the form. If you want to ensure that one of these two values ​​in the form can be submitted (ie "yes" or "no"), use a radio button instead.

single button

<input type="radio" v-model="pick" v-bind:value="a">

// when selected
vm.pick === vm.a

selection box options

<select v-model="selected">
    <!-- inline object literals -->
  <option v-bind:value="{ number: 123 }">123</option>
</select>

// when selected
typeof vm.selected // => 'object'
vm.selected.number // => 123

modifier

.lazy

By default, v-model synchronizes the value of the input box with the data after each input event is fired (except when the above input method combines text). You can add the lazy modifier to instead synchronize after the change event:

<!-- exist" change"sometimes instead of " input"update from time to time -->
<input v-model.lazy="msg">

.number

If you want to automatically convert the user's input value to a numeric type, you can add the number modifier to v-model:

<input v-model.number="age" type="number">

This is often useful because the value of an HTML input element will always return a string even when type="number". If the value cannot be parsed by parseFloat(), the original value will be returned.

.trim

If you want to automatically filter the leading and trailing whitespace characters entered by the user, you can add the trim modifier to v-model:

<input v-model.trim="msg">

Use v-model on components

If you are not yet familiar with Vue components, you can skip this for now.

HTML's native input element types don't always suffice. Fortunately, Vue's component system allows you to create reusable input components with fully custom behavior. These input components can even be used with v-model!

To learn more, see the Components Guide custom input component.