Guide

Form Input Bindings

Basics Usage

You can use the v-model directive to create two-way data bindings on form input elements. It automatically picks the correct way to update the element based on the input type. Although a bit magical, v-model is essentially syntax sugar for updating data on user input events, plus special care for some edge cases.

Text

<span>Message is: {{ message }}</span>
<br>
<input type="text" v-model="message" placeholder="edit me">
Message is: {{ message }}

Checkbox

Single checkbox, boolean value:

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

Mutiple 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 | json }}</span>
new Vue({
  el: '...',
  data: {
    checkedNames: []
  }
})

Checked names: {{ checkedNames | json }}

Radio

<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>


Picked: {{ picked }}

Select

Single select:

<select v-model="selected">
  <option selected>A</option>
  <option>B</option>
  <option>C</option>
</select>
<span>Selected: {{ selected }}</span>
Selected: {{ selected }}

Multiple select (bound to Array):

<select v-model="selected" multiple>
  <option selected>A</option>
  <option>B</option>
  <option>C</option>
</select>
<br>
<span>Selected: {{ selected | json }}</span>

Selected: {{ selected | json }}

Dynamic options rendered 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' }
    ]
  }
})
Selected: {{ selected }}

Value Bindings

For radio, checkbox and select options, the v-model binding values are usually static strings (or booleans for checkbox):

<!-- `picked` is a string "a" when checked -->
<input type="radio" v-model="picked" value="a">

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

<!-- `selected` is a string "abc" when selected -->
<select v-model="selected">
  <option value="abc">ABC</option>
</select>

But sometimes we may want to bind the value to a dynamic property on the Vue instance. We can use v-bind to achieve that. In addition, using v-bind allows us to bind the input value to non-string values.

Checkbox

<input
  type="checkbox"
  v-model="toggle"
  v-bind:true-value="a"
  v-bind:false-value="b">
// when checked:
vm.toggle === vm.a
// when unchecked:
vm.toggle === vm.b

Radio

<input type="radio" v-model="pick" v-bind:value="a">
// when checked:
vm.pick === vm.a

Select Options

<select v-model="selected">
  <!-- inline object literal -->
  <option v-bind:value="{ number: 123 }">123</option>
</select>
// when selected:
typeof vm.selected // -> 'object'
vm.selected.number // -> 123

Param Attributes

lazy

By default, v-model syncs the input with the data after each input event. You can add a lazy attribute to change the behavior to sync after change events:

<!-- synced after "change" instead of "input" -->
<input v-model="msg" lazy>

number

If you want user input to be automatically persisted as numbers, you can add a number attribute to your v-model managed inputs:

<input v-model="age" number>

debounce

The debounce param allows you to set a minimum delay after each keystroke before the input’s value is synced to the model. This can be useful when you are performing expensive operations on each update, for example making an Ajax request for type-ahead autocompletion.

<input v-model="msg" debounce="500">
{{ msg }}

Note that the debounce param does not debounce the user’s input events: it debounces the “write” operation to the underlying data. Therefore you should use vm.$watch() to react to data changes when using debounce. For debouncing real DOM events you should use the debounce filter.

← Methods and Event Handling Transitions →
Caught a mistake or want to contribute to the documentation? Edit this page on Github!