Skip to content
On this page

useVModel

Category
Export Size
1.06 kB
Last Changed
4 months ago
Related

Shorthand for v-model binding, props + emit -> ref

Usage

js
import { useVModel } from '@vueuse/core'

export default {
  setup(props, { emit }) {
    const data = useVModel(props, 'data', emit)

    console.log(data.value) // props.data
    data.value = 'foo' // emit('update:data', 'foo')
  },
}
import { useVModel } from '@vueuse/core'

export default {
  setup(props, { emit }) {
    const data = useVModel(props, 'data', emit)

    console.log(data.value) // props.data
    data.value = 'foo' // emit('update:data', 'foo')
  },
}

<script setup>

vue
<script lang="ts" setup>
import { useVModel } from '@vueuse/core'

const props = defineProps<{
  modelValue: string
}>()
const emit = defineEmits(['update:modelValue'])

const data = useVModel(props, 'modelValue', emit)
</script>
<script lang="ts" setup>
import { useVModel } from '@vueuse/core'

const props = defineProps<{
  modelValue: string
}>()
const emit = defineEmits(['update:modelValue'])

const data = useVModel(props, 'modelValue', emit)
</script>

Type Declarations

Show Type Declarations
typescript
export interface UseVModelOptions<T> {
  /**
   * When passive is set to `true`, it will use `watch` to sync with props and ref.
   * Instead of relying on the `v-model` or `.sync` to work.
   *
   * @default false
   */
  passive?: boolean
  /**
   * When eventName is set, it's value will be used to overwrite the emit event name.
   *
   * @default undefined
   */
  eventName?: string
  /**
   * Attempting to check for changes of properties in a deeply nested object or array.
   * Apply only when `passive` option is set to `true`
   *
   * @default false
   */
  deep?: boolean
  /**
   * Defining default value for return ref when no value is passed.
   *
   * @default undefined
   */
  defaultValue?: T
  /**
   * Clone the props.
   * Accepts a custom clone function.
   * When setting to `true`, it will use `JSON.parse(JSON.stringify(value))` to clone.
   *
   * @default false
   */
  clone?: boolean | CloneFn<T>
}
/**
 * Shorthand for v-model binding, props + emit -> ref
 *
 * @see https://vueuse.org/useVModel
 * @param props
 * @param key (default 'value' in Vue 2 and 'modelValue' in Vue 3)
 * @param emit
 */
export declare function useVModel<
  P extends object,
  K extends keyof P,
  Name extends string
>(
  props: P,
  key?: K,
  emit?: (name: Name, ...args: any[]) => void,
  options?: UseVModelOptions<P[K]>
): Ref<UnwrapRef<P[K]>> | WritableComputedRef<P[K]>
export interface UseVModelOptions<T> {
  /**
   * When passive is set to `true`, it will use `watch` to sync with props and ref.
   * Instead of relying on the `v-model` or `.sync` to work.
   *
   * @default false
   */
  passive?: boolean
  /**
   * When eventName is set, it's value will be used to overwrite the emit event name.
   *
   * @default undefined
   */
  eventName?: string
  /**
   * Attempting to check for changes of properties in a deeply nested object or array.
   * Apply only when `passive` option is set to `true`
   *
   * @default false
   */
  deep?: boolean
  /**
   * Defining default value for return ref when no value is passed.
   *
   * @default undefined
   */
  defaultValue?: T
  /**
   * Clone the props.
   * Accepts a custom clone function.
   * When setting to `true`, it will use `JSON.parse(JSON.stringify(value))` to clone.
   *
   * @default false
   */
  clone?: boolean | CloneFn<T>
}
/**
 * Shorthand for v-model binding, props + emit -> ref
 *
 * @see https://vueuse.org/useVModel
 * @param props
 * @param key (default 'value' in Vue 2 and 'modelValue' in Vue 3)
 * @param emit
 */
export declare function useVModel<
  P extends object,
  K extends keyof P,
  Name extends string
>(
  props: P,
  key?: K,
  emit?: (name: Name, ...args: any[]) => void,
  options?: UseVModelOptions<P[K]>
): Ref<UnwrapRef<P[K]>> | WritableComputedRef<P[K]>

Source

SourceDocs

Contributors

Anthony Fu
Jelf
webfansplz
Eduardo Wesley
Roman Meshcheryakov
久染
chaii3
Tmk
wheat
sondh0127
Zenthae
Eduardo San Martin Morote
lstoeferle
Alex Kozack
Homyee King
Prabu Rangki
Leonidas Arvanitis
yangger

Changelog

v9.2.0 on 9/5/2022
369e1 - feat: support clone option (#2022)
v8.9.3 on 7/14/2022
10f5a - fix: fix compact with 2.7, fix #1745 (#1898)
71550 - fix!: rename type VModelOptions to UseVModelOptions (#1894)
v8.9.2 on 7/12/2022
53319 - feat: compact with 2.7, fix #1745 (#1798)
v8.5.0 on 5/16/2022
70d80 - fix: unified value (#1568)
v8.4.2 on 5/5/2022
50d8a - fix: return default value when it's nil only (#1567)
f4e88 - fix: defaultValue can work with null (#1565)
v8.4.1 on 5/4/2022
0f3dd - fix: returning undefined on false values (#1557)
v8.4.0 on 5/3/2022
66e82 - feat: add option to define defaultValue (#1537)

Released under the MIT License.