v-model on Form Inputs

The binding contract

Vue's v-model gives a form control a two-way connection to reactive state. On a native text input, the familiar syntax is shorthand for binding the element's value and listening for its input event. When the user types, Vue updates the model; when application code changes the model, Vue updates the displayed value. The model is the source of truth after mounting, so changing the DOM directly is not a substitute for changing the reactive state.

<script setup>
import { ref } from 'vue'

const email = ref('')
</script>

<template>
  <label for="email">Email</label>
  <input id="email" v-model.trim="email" type="email" autocomplete="email">
  <p>Current value: {{ email }}</p>
</template>

The label is still essential: v-model synchronizes data, not accessibility. A label gives the control an accessible name, while a stable id lets assistive technology and users identify it. Input attributes such as type, autocomplete, required, and name continue to matter because they supply browser behavior, keyboard hints, form submission semantics, and autofill support.

Textareas and selects use the same directive but their native events differ. A textarea's content is represented by its value, not by interpolated text between its tags. A select's model is the selected option value. Prefer explicit option values when the stored value must be stable; otherwise an option's text can become the model and a copy edit can accidentally change application behavior. For a multi-select, the model is an array of selected option values.

Modifiers and value conversion

Modifiers adjust when data is synchronized or how it is interpreted. The trim modifier removes surrounding whitespace before the value reaches the model, which is useful for names and search terms but not appropriate for fields where whitespace itself is meaningful. The lazy modifier waits for the change event instead of updating on every input event. That can reduce expensive downstream work, but it also means the model may lag behind what is visibly typed until the control loses focus or the user commits the change.

The number modifier attempts numeric conversion. It is commonly used for quantities, but an empty field is still a meaningful state and conversion may leave a value as a string when it cannot be parsed. Code should validate the model rather than assume that the modifier guarantees a valid number. Vue also applies number conversion to input elements whose type is number. Treat that behavior as convenient parsing, not as domain validation: minimums, integer-only rules, safe ranges, and server-side validation remain application responsibilities.

Native controls have special value behavior. A checkbox with a boolean model toggles true or false. If its model is an array, checked boxes contribute their configured values to that array. Radio inputs that share a model select one value from a group. These are not merely text inputs with different styling; model initialization and value attributes determine the resulting data shape. A checkbox group should begin with an empty array, while a radio group can begin with null when no selection is valid yet.

Event timing and composition

The browser emits input events while text changes. Some writing systems use an input method editor (IME) to compose a character from several keystrokes. During composition, Vue avoids treating every intermediate string as a final value; synchronization occurs when composition ends. This behavior prevents partially composed text from triggering filtering, validation, or network requests as if it were complete. If an application needs to react to intermediate composition state, handle composition events deliberately and test with an IME rather than relying on ordinary keyboard tests.

Avoid attaching a second input handler that independently writes the same model unless there is a clear reason. Two update paths can disagree about trimming, normalization, or event timing. Use a computed value for derived display state, a watcher for an actual side effect, and an explicit event handler when the interaction is more than simple synchronization. This separation keeps v-model responsible for editing state while validation, persistence, and derived calculations remain visible in the code that owns those policies.

The reliable mental model is small: the control edits a reactive value; Vue handles the native event wiring; modifiers adjust synchronization or parsing; and the application still owns meaning, validation, accessibility, and persistence. With that contract clear, a form can use native controls without coupling business rules to DOM details.

Build a small registration form

A useful form example has more than a text box: it has fields with different value shapes, validation, and a submission boundary. The following Vue single-file component models a workspace request. Text fields remain strings, seats are parsed as a number, the region comes from a select, and notification channels form an array. The submit handler receives the model and makes a snapshot before starting asynchronous work.

<script setup>
import { computed, reactive, ref } from 'vue'

const form = reactive({
  name: '',
  seats: 1,
  region: 'us-east',
  channels: [],
})
const pending = ref(false)
const message = ref('')

const canSubmit = computed(() =>
  form.name.trim().length > 0 &&
  Number.isInteger(form.seats) && form.seats >= 1 &&
  form.region.length > 0
)

async function submit() {
  if (!canSubmit.value || pending.value) return
  pending.value = true
  message.value = ''
  const payload = { ...form, channels: [...form.channels] }
  try {
    await saveWorkspace(payload)
    message.value = 'Request saved.'
  } catch {
    message.value = 'The request could not be saved. Try again.'
  } finally {
    pending.value = false
  }
}

async function saveWorkspace(payload) {
  // Replace with the application's API client.
  await Promise.resolve(payload)
}
</script>

<template>
  <form @submit.prevent="submit">
    <label for="workspace-name">Workspace name</label>
    <input id="workspace-name" v-model.trim="form.name" required>

    <label for="seats">Seats</label>
    <input id="seats" v-model.number="form.seats" type="number" min="1" step="1">

    <label for="region">Region</label>
    <select id="region" v-model="form.region">
      <option value="us-east">US East</option>
      <option value="eu-west">EU West</option>
    </select>

    <fieldset>
      <legend>Notifications</legend>
      <label><input v-model="form.channels" type="checkbox" value="email"> Email</label>
      <label><input v-model="form.channels" type="checkbox" value="sms"> SMS</label>
    </fieldset>

    <button :disabled="!canSubmit || pending" type="submit">
      {{ pending ? 'Saving…' : 'Create workspace' }}
    </button>
    <p role="status" aria-live="polite">{{ message }}</p>
  </form>
</template>

This example keeps field editing declarative and moves the asynchronous boundary into one function. The form's submit modifier prevents a page navigation, and the pending flag blocks duplicate submissions while the request is running. The computed predicate offers immediate feedback, but it is not a security boundary: the API must repeat validation because clients can be modified or bypassed. A production UI should also associate field-specific error text with the relevant input and preserve entered values when a request fails.

The checkbox group illustrates how the initial model controls the result. Because channels begins as an array, choosing both options produces an array containing both values. If it instead began as false, the control would not represent a multi-selection. Radio groups follow a different pattern: give each radio the same v-model and a distinct value, then the model contains the selected value rather than an array. A single consent checkbox normally uses a boolean and should not be confused with a group.

Reset, defaults, and dynamic controls

For a reset action, restore the reactive model explicitly. The browser's native reset operation changes displayed controls to their original HTML defaults, which can leave the DOM and Vue's state out of sync. A reset function should assign a known initial object, clear errors and status messages, and decide whether any server-provided defaults should be reapplied. If a form has repeatable rows, update the array in state and render those rows with stable keys; directly inserting or removing DOM nodes bypasses Vue's rendering model.

Select option values deserve particular attention. A numeric-looking option value written in HTML is ordinarily a string unless it is bound as an expression. If downstream code needs a number, bind the value explicitly or normalize at the submit boundary. The same principle applies to dates and custom values: decide the model's type intentionally instead of depending on how the control serializes its value.

An effective exercise is to change one property at a time. Remove the array initializer and observe the checkbox-group behavior. Replace v-model.number with plain v-model and inspect the runtime type. Change the select's options and verify that the initial model still matches one of them. Then simulate a rejected save and confirm that pending resets, the user can retry, and the form contents remain intact. These checks reveal whether the state contract is clear rather than merely making the happy path appear to work.

Keep parsing separate from validation

v-model is a synchronization tool, not a complete form framework. Its convenience can hide an important boundary: the value held while a person edits a field is not necessarily the validated value accepted by the application. A numeric field may be blank, partially entered, outside its allowed range, or represented as a string after failed conversion. If the UI must preserve intermediate text exactly, model the text as a string and parse it when validating or submitting. If number conversion is appropriate during editing, still check finiteness, integer requirements, and business limits before sending data.

Whitespace handling has similar consequences. The trim modifier is useful for identifiers whose surrounding whitespace should be ignored, but trimming a password or a free-form note would silently change user input. The lazy modifier reduces updates but can make a live preview or error state appear stale. Choose modifiers from the interaction contract, not from a rule that every field should use the same set. For expensive work such as remote search, keep the input responsive and debounce the side effect rather than delaying the model without considering the user experience.

Component models and explicit APIs

Native input behavior does not automatically define how a custom component participates in v-model. A component model has a prop and an update event contract; in current Vue versions, defineModel can express that contract succinctly. A reusable component can expose a value while still owning presentation, but it should document its emitted type and avoid mutating a prop directly. Named models are useful when a component has independent editable values. They should not be used to create an opaque bag of state that callers cannot understand.

For example, a date-range component might expose start and end models, but a single object model can be clearer when both values must change atomically. The choice affects validation and update semantics. A component that emits partial updates can briefly expose an invalid range; one that emits a complete range can validate the pair before notifying its parent. The parent should remain responsible for persistence and business decisions, while the component owns the interaction mechanics it can safely encapsulate.

Accessibility, testing, and debugging

Every model still needs a usable control. Give each input a programmatic label, group related choices with fieldset and legend, expose errors in text, and connect an error to its control with aria-describedby when applicable. Do not communicate invalid state only through color. A disabled submit button can prevent an invalid action, but it should not be the only explanation for what needs attention. Native required and type attributes improve browser affordances; they do not replace accessible error messages or server checks.

Test behavior through user interactions rather than assigning to component internals. For a text input, enter a value and assert that the rendered state changes. For a checkbox array, toggle multiple options and verify both membership and removal. For a number field, test empty input, valid integers, decimals, and out-of-range values. For a select, assert the model after a change. Then test submission, pending state, rejection, and reset. These cases catch type assumptions that a single happy-path snapshot cannot reveal.

When debugging, inspect the model's runtime value and the actual DOM event before adding another handler. Confirm the correct initial type, input value attribute, modifier, and event timing. If state changes but the display does not, check whether code mutated a non-reactive copy or whether a component failed to emit its update event. If the display changes but the submitted payload is stale, inspect whether the handler copied state before the latest update or whether lazy synchronization was chosen intentionally.

Decision rule

Use native v-model when the control's editing behavior maps cleanly to a reactive value. Use explicit input events when every keystroke has a specialized meaning, when parsing must preserve intermediate input, or when updates need a transaction that spans several fields. Add a form library when many forms share complex schema rules, touched and dirty tracking, nested arrays, or server-error mapping. A library introduces conventions and dependencies, so a small form with a few fields is often easier to maintain with native controls and explicit validation.

In an interview, explain the data shape first, then the synchronization event, then the validation boundary. A strong example distinguishes a checkbox boolean from a checkbox-group array, describes why a number modifier does not validate a quantity, and mentions accessibility and server-side checks. That answer demonstrates that v-model is understood as one part of a form architecture rather than as magic that makes all input concerns disappear.