1---
2category: Component
3---
4 
5# useVModel
6 
7Shorthand for v-model binding, props + emit -> ref
8 
9> We encourage you to use Vue's [`defineModel`](https://vuejs.org/api/sfc-script-setup.html#definemodel) over this composable, however there are some edge-cases like using `TSX` or the `deep: true` option that `defineModel` doesn't support.
10 
11## Usage
12 
13```ts
14import { useVModel } from '@vueuse/core'
15 
16const props = defineProps<{
17  modelValue: string
18}>()
19const emit = defineEmits(['update:modelValue'])
20 
21const data = useVModel(props, 'modelValue', emit)
22```
23 
24### Options API
25 
26```ts
27import { useVModel } from '@vueuse/core'
28 
29export default {
30  setup(props, { emit }) {
31    const data = useVModel(props, 'data', emit)
32 
33    console.log(data.value) // props.data
34    data.value = 'foo' // emit('update:data', 'foo')
35  },
36}
37```
38 
39## Options
40 
41### Passive Mode
42 
43By default, `useVModel` returns a computed ref. In passive mode, it creates a local ref that syncs with the prop via `watch`, allowing deep reactivity tracking.
44 
45```ts
46const data = useVModel(props, 'modelValue', emit, { passive: true })
47```
48 
49### Deep Watching
50 
51When using `passive: true`, you can enable deep watching for nested object changes:
52 
53```ts
54const data = useVModel(props, 'modelValue', emit, {
55  passive: true,
56  deep: true,
57})
58```
59 
60### Clone Values
61 
62Clone the prop value to avoid mutating the original object. Set to `true` to use `JSON.parse(JSON.stringify())` or provide a custom clone function.
63 
64```ts
65const data = useVModel(props, 'modelValue', emit, {
66  clone: true,
67  // or provide custom clone function
68  // clone: (val) => structuredClone(val),
69})
70```
71 
72### Default Value
73 
74Provide a default value when the prop is undefined:
75 
76```ts
77const data = useVModel(props, 'modelValue', emit, {
78  defaultValue: 'default',
79})
80```
81 
82### Custom Event Name
83 
84Override the default `update:propName` event name:
85 
86```ts
87const data = useVModel(props, 'value', emit, {
88  eventName: 'change',
89})
90```
91 
92### Emit Validation
93 
94Use `shouldEmit` to validate before emitting. Return `false` to prevent the emit:
95 
96```ts
97const data = useVModel(props, 'modelValue', emit, {
98  shouldEmit: (value) => {
99    // Only emit if value is valid
100    return value.length > 0
101  },
102})
103```
104 
105## Type Declarations
106 
107```ts
108export interface UseVModelOptions<T, Passive extends boolean = false> {
109  /**
110   * When passive is set to `true`, it will use `watch` to sync with props and ref.
111   * Instead of relying on the `v-model` or `.sync` to work.
112   *
113   * @default false
114   */
115  passive?: Passive
116  /**
117   * When eventName is set, it's value will be used to overwrite the emit event name.
118   *
119   * @default undefined
120   */
121  eventName?: string
122  /**
123   * Attempting to check for changes of properties in a deeply nested object or array.
124   * Apply only when `passive` option is set to `true`
125   *
126   * @default false
127   */
128  deep?: boolean
129  /**
130   * Defining default value for return ref when no value is passed.
131   *
132   * @default undefined
133   */
134  defaultValue?: T
135  /**
136   * Clone the props.
137   * Accepts a custom clone function.
138   * When setting to `true`, it will use `JSON.parse(JSON.stringify(value))` to clone.
139   *
140   * @default false
141   */
142  clone?: boolean | CloneFn<T>
143  /**
144   * The hook before triggering the emit event can be used for form validation.
145   * if false is returned, the emit event will not be triggered.
146   *
147   * @default undefined
148   */
149  shouldEmit?: (v: T) => boolean
150}
151/**
152 * Shorthand for v-model binding, props + emit -> ref
153 *
154 * @see https://vueuse.org/useVModel
155 * @param props
156 * @param key (default 'modelValue')
157 * @param emit
158 * @param options
159 *
160 * @__NO_SIDE_EFFECTS__
161 */
162export declare function useVModel<
163  P extends object,
164  K extends keyof P,
165  Name extends string,
166>(
167  props: P,
168  key?: K,
169  emit?: (name: Name, ...args: any[]) => void,
170  options?: UseVModelOptions<P[K], false>,
171): WritableComputedRef<P[K]>
172export declare function useVModel<
173  P extends object,
174  K extends keyof P,
175  Name extends string,
176>(
177  props: P,
178  key?: K,
179  emit?: (name: Name, ...args: any[]) => void,
180  options?: UseVModelOptions<P[K], true>,
181): Ref<UnwrapRef<P[K]>>
182```
183