useVModel
Implements a controlled / uncontrolled prop contract for any component prop bound via v-model. When the parent provides both the prop and the matching onUpdate:prop listener the component operates in controlled mode; otherwise it manages its own internal ref. Supports kebab-case / camelCase prop alias pairs and optional in/out value transformers.
API
Signature
Full TypeScript signature sourced from the composable file.
useVModel is the backbone of every form control in origam. It handles the subtle Vue 3 contract where a component is only "controlled" when BOTH the prop and the update listener are present on `vnode.props` — passing the prop alone without a handler keeps the component uncontrolled.
API
Parameters
Input parameters accepted by this composable.
- propsrequiredProps
- The component props object returned by defineProps. The composable reads `props[prop]` and inspects `vm.vnode.props` to detect whether the listener is wired.
- proprequiredProp
- The prop key to observe, e.g. `"modelValue"` for a standard v-model binding.
- defaultValueMaybeRefOrGetter<Props[Prop] | undefined>
- Value used to initialise the internal ref when the prop is undefined on first render.
- transformIn(value?: Props[Prop]) => Inner(v?: Props[Prop]) => v as Inner
- Optional transform applied to the external prop value before exposing it to the component. Useful for converting a string to a number, or normalising null / undefined.
- transformOut(value: Inner) => Props[Prop](v: Inner) => v as Props[Prop]
- Optional inverse transform applied before emitting `update:prop`. Pairs with transformIn to keep the internal representation separate from the public API value.
API
Return values
Properties and methods exposed by the composable return object.
- (model)
- A writable computed ref. Reading it returns the current value (controlled or internal). Writing it updates the internal ref and emits `update:prop`. The `externalValue` accessor returns the raw prop value without transformIn applied.
Usage
Examples
Ready-to-paste usage snippets.
Boolean toggle with v-model
String prop with value transform