Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 87 ยท Forms and User Input

Two-Way Binding with v-model

Learn Vue v-model for text, textarea, checkbox, radio, select and multiple select, how it desugars to a value binding plus an event listener, and the lazy, number and trim modifiers.

A form field is a two-way street. The page must show the value that lives in your state, and when the user types, your state must learn about it. Doing that by hand means a value binding, an event listener and a handler for every single input. Vue's v-model directive does both halves with one attribute.

You will meet v-model in nearly every Vue app, so it is worth knowing exactly what it does for each kind of form control, and what it compiles to. The state it binds to is ordinary ref or reactive state; the value binding underneath is the v-bind you already know, and the listener is a v-on event handler.

What v-model really is

v-model is shorthand for a one-way binding plus an event listener. For a text input, these two lines are equivalent:

HTML
<input v-model="text" />

<input :value="text" @input="text = $event.target.value" />

State flows into the element through :value; user input flows back through the input event. Whenever the state changes, the input shows the new text.

flowchart LR
    S["Your state<br/>text"] -->|"value binding"| I["Input element"]
    I -->|"input event updates"| S

v-model connects the state and the element in both directions.

Two rules follow from this model:

  • The state is the source of truth. v-model ignores the initial value, checked and selected attributes of the element. Set starting values in your JavaScript (const text = ref("hello")), not in the HTML.
  • Each type of control uses the right property and event under the hood, so you do not have to remember them. They differ, which is why v-model is convenient:
Element Property bound Event listened to
text input, textarea value input
checkbox, radio checked change
select value change

Text and textarea

For single-line and multi-line text, bind to a string. In a textarea, write v-model; text interpolation between the tags (<textarea>{{ bio }}</textarea>) does not work.

HTML
<input v-model="name" />
<textarea v-model="bio" rows="3"></textarea>

One detail: while a user is composing text with an input method editor (for Chinese, Japanese or Korean, for example), v-model waits until the composition ends. If you need updates during composition, use the manual :value and @input pair.

Checkboxes and radio buttons

A single checkbox binds to a boolean. A group of checkboxes binds to an array, and each box needs a value: ticking a box adds its value to the array, unticking removes it. Radio buttons share one variable, and the selected radio's value is stored.

HTML
<input type="checkbox" v-model="subscribed" />                    <!-- true or false -->
<input type="checkbox" value="vue" v-model="interests" />        <!-- array of strings -->
<input type="radio" value="pro" v-model="plan" />                 <!-- one string -->

Single checkboxes can store other values than true and false with true-value and false-value: <input type="checkbox" v-model="answer" true-value="yes" false-value="no" />.

Select and multiple select

On a select, put v-model on the select itself, not on the options. A plain select stores one value; with the multiple attribute it stores an array.

HTML
<select v-model="country">
  <option disabled value="">Choose a country</option>
  <option value="fi">Finland</option>
  <option value="ca">Canada</option>
</select>

Always add the disabled option with value="" as a placeholder. If the bound value matches no option, the select shows nothing, and some browsers (iOS Safari) would then not fire a change event for the first option.

Option values can also be bound with :value, so they can be numbers or objects, not only strings: <option :value="{ id: 1 }">.

A complete form in one place

The example below uses one reactive object for the whole form and shows its live content under the controls.

v-model with every kind of control

Type in the name box and watch the JSON change on every keystroke. Tick one more interest and the array gains an item; untick "Vue" and it is removed. The single checkbox flips between true and false, the radios store "free" or "pro", and in the multiple select the array holds every highlighted option.

Modifiers: lazy, number and trim

Modifiers adjust how v-model reads the value. Write them after the directive name with dots.

  • .lazy syncs on the change event (usually when the field loses focus or Enter is pressed) instead of on every input.
  • .number converts the text with parseFloat. If the text cannot be parsed, you keep the original string. (An <input type="number"> already gives you a number in most cases, and .number is applied automatically to it.)
  • .trim removes whitespace from both ends of the text.

They can be combined: v-model.trim.lazy="query".

Desugared v-model and the three modifiers

Experiment with the fields. Typing in either of the first two inputs updates both, because the hand-written pair behaves like v-model. The .lazy field only updates the state line after you leave it. Typing 42 into the second age box gives typeof: number and plus 1 = 43, whereas the first age box reports string. Typing hi in the last field shows [hi] length 2.

Common mistakes

  • Setting value or checked in the HTML and expecting it to be the initial state. v-model ignores it.
  • Using v-model on a non-field element (such as div). It works on input, textarea and select, and on components that support it (see v-model on Components).
  • Binding a checkbox group to a string instead of an array. With a non-array value the group acts like a single boolean checkbox.
  • Mixing v-model with :value on the same input. v-model already controls value, so the second binding fights it.
  • Forgetting that .number still returns a string when the text is not numeric. Validate the value; see Building Forms.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which pair of attributes is equivalent to <input v-model="text" />?

    A text input is bound with its value property and updated from the input event. v-model generates exactly that pair.
  2. 2. You have three checkboxes with different value attributes, all with v-model="picked". What type should picked be?

    Checkboxes sharing a v-model bind to an array. Ticking adds the box's value, unticking removes it.
  3. 3. Where does v-model go on a dropdown with several options?

    v-model belongs on the select. The options only provide the possible values.
  4. 4. What does v-model.number do when the user types abc?

    The number modifier calls parseFloat on the text. If the result cannot be parsed, Vue leaves the value as the original string.
  5. 5. You write <input v-model="name" value="Grace" /> with const name = ref(''). What does the input show on load?

    The state is the source of truth, so the initial value attribute is ignored. Put the starting text in the ref.

Summary

  • v-model is a value binding plus an event listener, kept in sync with your state in both directions.
  • Text and textarea use value and input; checkboxes and radios use checked and change; selects use value and change.
  • A single checkbox gives a boolean, a group of checkboxes gives an array, radios give one value, and select multiple gives an array.
  • The state is the source of truth: v-model ignores initial value, checked and selected attributes.
  • .lazy syncs on change, .number runs parseFloat, and .trim strips surrounding whitespace.
  • You can always write the same thing by hand with :value and @input when you need extra control.

Next, put these controls together into complete forms in Building Forms.