Listening to external programmatic model mutations with defineModel

[8ctavio]

Hi, I'd like to discuss how/why to listen to a custom component's model external programmatic mutations.

When authoring a form field component with defineModel, new values for the component's model may be obtained from two sources:

1. Internal: Typically changes or interaction with elements mounted in the component
2. External: Programmatic model mutations in parent component

When a new value is obtained, additional operations may be required before or after updating the component's model. Moreover, these operations might vary depending on the new value's source.

Two examples

1. Calendar component

Consider a Vue component to wrap a package's Javascript-only calendar. The package's API allows to define event handlers where the model value can be updated according to the calendar's selected date. However, if the parent mutates the model value, it would be required to update the calendar's state to reflect that change. This is only the case for external changes since internal changes due to calendar interaction automatically update calendar's state.

function onInternalUpdate(v){
    model.value = v
}
function onExternalUpdate(v){
    updateCalendarState(v)
    model.value = v
}

2. Number input component

Consider a Vue component for a number input whose model value is of type number but the underlying input element's value is a formatted version of the number. Every time the input's input event is emitted or the parent mutates the model value, the formatted number version must be computed.

function onInternalUpdate(v){
    formatted.value = formatNumber(v)
    model.value = parseNumber(v)
}
function onExternalUpdate(v){
    formatted.value = formatNumber(v)
    model.value = parseNumber(v)
}

The problem

In order to properly handle internal and external changes it is required to independently listen to changes from each source. Listening to internal changes is straightforward; usually achieved through event handlers for mounted elements. It is not completely clear, however, how to properly listen for external changes.

Using watch

Since the model obtained from defineModel is a ref (synced with the parent), an option to detect external mutations is simply using watch(model, onExternalUpdate). However, with this approach there would inevitably be additional overhead since, by design, the model is not exclusively mutated externally but also internally as a result of either internal or external changes.

model updated as a result of internal changes

When onExternalUpdate is called due to a local model update, there are two possibilities:

1. Let onExternalUpdate run (i.e., do nothing). The execution of onExternalUpdate due to local model updates might not produce adverse side effects. However, unnecesary operations would always be performed every time model is internally updated (see example 1).
2. To prevent execution of onExternalUpdate operations, an internalModel ref might be implemented to handle internal changes. When internalModel is updated, model should be updated accordingly. Then, in onExternalUpdate, if model.value === internalModel.value it may be assumed that the change was produced internally, so the callback operations can be skipped. Of course, for some applications, this assumption may prove to be insufficient. Furthermore, for some model values, testing for equality is not so straightforward.

model updated as a result of external changes

Sometimes, model might be further updated inside onExternalUpdate. This will rerun the callback. Again, there are two possibilities:

1. Let onExternalUpdate run (i.e., do nothing). If the re-execution of onExternalUpdate updates model with its current value no further adverse side effects are produced. Again, the problem is performing unnecesary operations before the model is re-updated (see example 2).
2. In some cases, a validation of the new model value might be sufficient to skip callback operations. For example, if in the first callback execution the model is formatted, at the second execution it may be verified if the model is already formatted.

In short, onExternalUpdate will be also called for internal model updates. These additional calls will either perform unnecesary work or require additional verificaction to skip operations. In any case, overhead is present.

Even though functionality is achievable and in some cases overhead might be neglected, using watch(model, onExternalUpdate) simply does not seem to be the right approach.

Fundamental problem

The fundamental problem appears to be the way the component's model is defined. Currently, a custom component's model is defined in its parent. The parent is then responsible for providing the component's model to the component itself.

Using v-model seems to imply a parent's intent for the component to take full control over the model (at least for cases such as a form field component). Therefore, it would make sense to define the component's model in the component, and expose a read-only version and an update function for the parent to interact with the custom component's model. This way, the custom component could easily identify external mutations.

---

Below are three alternatives to listen to external programmatic model mutations.

1. Expose model with defineExpose

As previously described, an alternative is to define the model in the custom component and expose it with defineExpose.

// Component.vue
const model = ref()
function updateModel(v){ /* ... */ }

defineExpose({
    model: readonly(model),
    updateModel
})

Note that the component's model definition is analogous to defining modelValue and update:modelValue props (or using defineModel), but now the component has more control over how to update its model value.

<!-- Parent.vue -->
<script setup>
const component = ref(null)

// Read model value
component.value.model

// Update model value
component.value.updateModel(8)
</script>

<template>
    <Component ref="model" :initial="0"/>
</template>

However, the API to interact with the custom component's model becomes less convenient. A useModel composable to consume the exposed model may be introduced to improve API.

<!-- Parent.vue -->
<script setup>
const component = useModel(0)

// Read model value
component.value

// Update model value
component.value = 8
</script>

<template>
    <Component :ref="component.consumeExposed"/>
</template>

See full example.

Even though the concept of exposing the model from the custom component seems like a good approach, its implementation with available APIs present some drawbacks, so a better implementation is sought.

2. Provide function for component to register callback

Although conceptually there may be better approaches to defining a component's model in its parent, in practice it is by no means a limitation.

As seen in the previous alternative, it is desired for the component to be able to define a function to handle external programmatic model mutations. The parent could provide a function for the component to register a callback and use it to update the component's model.

The suggested API is presented below.

<!-- Parent.vue -->
<script setup>
const component = useModel(0)

// read model value
component.value

// update model value
component.value = 8
</script>

<template>
    <custom v-bind="component"/>
</template>

// Component.vue
const props = defineProps({
    onModelMutated: Function
})
const model = defineModel({
    get(modelRef){
        return modelRef.value
    }
})
props.onModelMutated(v => {
    /* external mutation */
})

For the parent the API is similar to using v-model. Model modifiers could be implemented as well, but they could not be so conveniently specified. For the component, the API requires some extra steps compared to only using defineModel.

See full example.

3. Provide custom object through v-model (modelValue prop)

Lastly, in order to reduce additional steps required for using component models, an object containing

• the model value,
• a function to update the model, and
• a function to register a callback for external programmatic mutations

may be sent directly as a prop. For convenience, v-model could be used to send the object in a modelValue prop; the update:modelValue prop should be ignored.

An additional composable analogous to defineModel may be implemented to properly consume the modelValue prop.

The suggested API is presented below.

<!-- Parent.vue -->
<script setup>
const component = useModel(0)

// read model value
component.value

// update model value
component.value = 8
</script>

<template>
    <custom v-model="component"/>
</template>

// Component.vue
const props = defineProps({
    modelValue: Object
})
const model = createModel(props.modelValue)
model.onMutated(v => {
    /* external mutation */
})

See full example.