Skip to content

useVModel

Category
Export Size
486 B
Last Changed
3 months ago
Related

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

We encourage you to use Vue's defineModel over this composable, however there are some edge-cases like using TSX or the deep: true option that defineModel doesn't support.

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')
  },
}

<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>

Type Declarations

Show Type Declarations
typescript
export interface UseVModelOptions<T, Passive extends boolean = false> {
  /**
   * 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?: Passive
  /**
   * 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>
  /**
   * The hook before triggering the emit event can be used for form validation.
   * if false is returned, the emit event will not be triggered.
   *
   * @default undefined
   */
  shouldEmit?: (v: T) => boolean
}
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], false>,
): WritableComputedRef<P[K]>
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], true>,
): Ref<UnwrapRef<P[K]>>

Source

SourceDocs

Contributors

Anthony Fu
Jelf
Anthony Fu
webfansplz
Shinigami
motian
objectisundefined
Alex Liu
白雾三语
Eduardo Wesley
Roman Meshcheryakov
久染
chaii3
Tmk
wheat
sondh0127
Zenthae
Eduardo San Martin Morote
lstoeferle
Alex Kozack
Homyee King
Prabu Rangki
Leonidas Arvanitis
yangger

Changelog

0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
48f4c - fix: clone set to true triggered infinite loop (#3097)
7d788 - feat: improve types overload (#3055)
cb644 - refactor!: remove isFunction and isString utils
f8a53 - feat: add shouldEmit hook (#2836)

Released under the MIT License.