Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 87 ยท Components

v-model on Components

Build custom form inputs in Vue 3 - how v-model works on a component with modelValue and update:modelValue, defineModel, multiple v-models with arguments and custom modifiers.

On a native input, v-model keeps a variable and a field in sync. The same directive works on your own components, which is what lets you build a date picker, a rating widget or a styled text field that the parent uses exactly like an <input>: <StarRating v-model="stars" />. The component hides how it works, and the parent gets two-way binding for free.

Underneath, component v-model is not magic. It is a prop going down and an event going up, with agreed names. Once you see that, writing custom inputs, using several v-models on one component, and adding your own modifiers all become straightforward.

How it desugars

On a component, this:

HTML
<CustomInput v-model="name" />

is shorthand for this:

HTML
<CustomInput :model-value="name" @update:model-value="name = $event" />

So the component must do two things: accept a prop called modelValue, and emit an event called update:modelValue with the new value whenever the user changes it. It never changes its prop; it asks the parent to change the variable, which then flows back down. This is the "props down, events up" rule applied to a very common case.

flowchart LR
  P["Parent: name = 'Ada'"] -- "modelValue prop" --> C["CustomInput"]
  C -- "update:modelValue event" --> P

One variable, kept in sync through a prop going down and an event going up.

A custom input with modelValue and update:modelValue

Type in either field and the paragraph updates. Click the button: the parent writes a new value, it flows down as modelValue, and the input shows it. The component holds no state of its own; it is a thin, reusable wrapper around a native <input>. Notice that it uses :value, not v-model, on the inner input: the value comes from the prop, and the input event reports changes upward.

A computed wrapper

Writing :value and @input is fine, but if you want to put v-model on the inner input (for example because it is a <select> or because you want modifiers like .trim to work), use a writable computed property (see computed properties) as the bridge:

JavaScript
setup(props, { emit }) {
  const value = computed({
    get: () => props.modelValue,
    set: (next) => emit("update:modelValue", next),
  });
  return { value };
}
// template: <input v-model="value">

Reading value reads the prop; writing to it emits the event. The inner v-model thinks it is talking to a normal variable.

defineModel: the short way

Since Vue 3.4, an SFC with <script setup> can replace the prop, the emit and the computed with one macro. defineModel() returns a ref that reads the prop and writes by emitting:

VUE
<script setup>
const model = defineModel()
</script>

<template>
  <input v-model="model" />
</template>

Assigning model.value = "x" emits update:modelValue for you. It also handles a subtle case: if the parent does not pass v-model at all, the ref still works as local state, so the component does not break when used standalone. You can pass options like a prop (defineModel({ type: Number, required: true })) and give the model a name (defineModel("title"), which uses the prop title and the event update:title).

The sandbox on this site has no SFC compiler, so the runnable examples write out what defineModel generates: the prop, the emit and (when useful) the computed. They behave identically.

Multiple v-models with arguments

A component can bind more than one value. Give each v-model an argument: v-model:first-name. The argument becomes the name of the prop (firstName) and of the event (update:firstName). The default, argument-less v-model is simply the argument modelValue.

Two v-models on one component

The parent keeps two independent variables and the child edits both through two separate prop and event pairs. The button changes both from outside and the inputs follow. With defineModel the child would simply have const first = defineModel("firstName") and const last = defineModel("lastName").

This is how libraries build range sliders (v-model:min, v-model:max), dialogs (v-model:open) and form groups. Prefer it over passing one object and mutating its fields, which would break the one-way rule from the props lesson.

Custom modifiers

Native v-model has .trim, .number and .lazy. A component can define its own modifiers. When a parent writes v-model.capitalize="text", Vue passes the modifiers to the component as a prop called modelModifiers, an object such as { capitalize: true }. The component reads it and applies the behavior before emitting.

For a model with an argument, the modifiers prop is named after it: v-model:title.capitalize arrives as titleModifiers.

A capitalize modifier for v-model

Type hello world in each field. The text appears with a capital H because the component applied the modifier before emitting. Both bindings use .capitalize, one through the default modelModifiers and the other through titleModifiers. In an SFC you get the same object from const [model, modifiers] = defineModel({ set(value) { ... } }), where the set option transforms the value just before it is emitted.

One catch is visible if you type quickly in the middle of the text: the component rewrites the whole value on every input, which can move the cursor in a real browser. Keep modifiers simple and cursor-safe (such as capitalizing the first letter, trimming on blur or rounding numbers), and reserve live reformatting (phone numbers, credit cards) for carefully tested components.

Design tips

  • Keep a custom input behaving like a native one: accept disabled, required and id through fallthrough attributes onto the real <input>, and keep the label association intact.
  • Emit the new value, not the event object, so the parent does not need to know how the control works internally.
  • Do not copy modelValue into local state unless you have a reason; that is the same copy-once trap described in props.
  • For forms with many fields, see form handling, where each field can be such a component.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which pair of names must a component use to support a plain v-model?

    v-model on a component compiles to :model-value and @update:model-value, so the component needs the prop modelValue and must emit update:modelValue.
  2. 2. What does v-model:first-name="first" bind?

    The argument names the prop and event: firstName and update:firstName. Plain v-model is the same thing with the argument modelValue.
  3. 3. Where does a component find the modifiers for a plain v-model.capitalize?

    Vue passes the modifiers in modelModifiers (or argumentModifiers when an argument is used). The component applies them itself.
  4. 4. What does defineModel() give you in a script setup component?

    defineModel is a macro that declares the prop and the event for you and returns a ref bound to both.
  5. 5. Why should the custom input use :value and @input on its inner input instead of v-model="modelValue"?

    Binding v-model directly to a prop would try to mutate it. The component must emit update:modelValue, or use a writable computed (or defineModel) as the bridge.

Summary

  • Component v-model is a prop modelValue plus an event update:modelValue; the component never mutates the prop.
  • A writable computed (get reads the prop, set emits) lets you use v-model on the inner input, and defineModel() does it all in SFCs since Vue 3.4.
  • Use arguments (v-model:first-name) for several independent bindings; they map to firstName and update:firstName.
  • Custom modifiers arrive as modelModifiers (or argumentModifiers) and are applied before emitting.
  • Keep custom inputs native-like: emit plain values and let attributes fall through to the real input.

Next: Slots