New composable and directive for parent to child object mutations: useDeepModel and v-deep-model

[michaelcozzolino]

• Start Date: (2025-02-25)
• Target Major Version: (3.x)
• Reference Issues: (fill in existing related issues, if any)
• Implementation PR: (leave this empty)

Edit: After many attempts in trying to make a draft for the directive I have to say that, at least to me and my knowledge, it's almost impossible to achieve it, as working with references(objects) will always end up in mutating the original object directly through the directive, even destructuring recursively and assigning the new value ended up in side effects when working with more than 1 input field. Same as for the composable, it works good if used in a non recursive way, meaning that you have to pass into it only the root object, if you want to edit a sub object you will have to create another component and pass through it the sub object, because passing the sub object directly in the composable and working with that might still mutate the property of a prop without realizing it, and it's very difficult if not impossible to ensure that it won't happen. So, to conclude, if you need to mutate deeply nested object properties through props, the best option is to go with a pinia/vuex store and there will be neither problems with reactivity nor with vue props mutation violations.

Summary

At the moment Vue does not provide any way to update the property of an object passed through props by using v-model
without breaking the parent -> child data flow. Even by using defineModel in the child component as in the following:

const obj = defineModel<{propertyA: string; propertyB: string}>({ required: true })
</script>

<template>
    <div>
        <input v-model="obj.propertyB">
    </div>
</template>

it would break the data flow, because no event is emitted, hence the data is updated because the object is a reference.
(https://vuejs.org/guide/components/props.html#mutating-object-array-props)

The goal is to ideally have a composable and a directive that are capable of working with objects deeply.

Basic example

Composable (useDeepModel)

// types.ts

export interface Person {
    name:     string;
    surname:  string;
    children: Person[];
}

<!-- Parent.vue -->

<template>
<Child v-model="person"  />
</template>

<script setup lang="ts">
import type { Person }   from './types';
import { ref } from 'vue';

const person = ref<Person>({
    name:     'michael',
    surname:  'cozzolino',
    children: [
        {
            name:     'first',
            surname:  'child',
            children: [],
        },
        {
            name:     'second',
            surname:  'child',
            children: [],
        },
    ],
});

<!-- Child.vue -->

<template>
    <div>
        <input v-model="editablePerson.name">
        <input v-model="editablePerson.surname">
        <input v-model="editablePerson.children[0].name">
    </div>
</template>

<script setup lang="ts">
import type { Person }     from './types';
import { useDeepModel } from './useDeepModel';

const person = defineModel<Person>({ required: true });
const editablePerson = useDeepModel(person);
</script>

directive (v-deep-model)

// types.ts

export interface Person {
    name:     string;
    surname:  string;
    children: Person[];
}

<!-- Parent.vue -->

<template>
<Child v-model="person"  />
</template>

<script setup lang="ts">
import type { Person }   from './types';
import { ref } from 'vue';

const person = ref<Person>({
    name:     'michael',
    surname:  'cozzolino',
    children: [
        {
            name:     'first',
            surname:  'child',
            children: [],
        },
        {
            name:     'second',
            surname:  'child',
            children: [],
        },
    ],
});

<!-- Child.vue -->

<template>
    <div>
        <input v-deep-model:name="editablePerson">

        <input v-deep-model:children:name="[editablePerson, index]">

        <input v-deep-model:name="[editablePerson.children, index]">
    </div>
</template>

<script setup lang="ts">
import type { Person }     from './types';

const person = defineModel<Person>({ required: true });
</script>

Motivation

Many times developers end up in having complex and big objects where the UI to build should manipulate and show their
data. It could be easy to work by just putting all the data in inputs in the same Vue component, so that the whole
data manipulation workflow doesn't need to update parent components where the data is passed to children.
This approach would yes, work, but at the end it would make the whole codebase to be complex and tricky to understand, so
developers start splitting the code in multiple components to handle the data being stored in one or multiple objects,
this requires the usage of two-way data binding approaches such as props + emits + assignment in the parent or
almost full automation of the former with defineModel, that even if it might seem appetizing, it lacks the possibility
of the partial object update so that if you have:

<!-- Child.vue -->

<template>
    <div>
        <input name="person-name-input" v-model="person.name">
    </div>
</template>

<script setup lang="ts">
import type { Person }     from './types';

const person = defineModel<Person>({ required: true });
</script>

this cannot be considered completely valid as there is no emitted event, instead what can be considered valid could be:

<!-- Child.vue -->

<template>
    <div>
        <input name="person-name-input" v-model="name">
    </div>
</template>

<script setup lang="ts">
import type { Person }     from './types';

const person = defineModel<Person>({ required: true });
const name = computed({
    get: () => person.name;
    set: (newName: string) => person.name = newName;
});
</script>

having these kinds of assignations makes the code verbose and complex to read if the object is big enough, as the developer
will have to replicate the same for every object property.

Detailed design

Both composable and directive, must work in a way that the parent component uses <Child v-model="object" />

Composable (useDeepModel)

The idea is to have a composable accepting the modelRef from the child (const modelRef = defineModel<Type>())
and returning a writable computed having a proxy whose setters automatically sets the new property through a complete
object update, and the setter of the writable computed will set the new object to the modelRef letting it automatically
emit the event related to the update (similar to what is explained here https://skirtles-code.github.io/vue-examples/patterns/computed-v-model):

export function useDeepModel<T extends object, M extends PropertyKey = string, G = T, S = T>(
  obj: ModelRef<T, M, G, S>,
): WritableComputedRef<T> {
  const o = computed({
    get: (): T => {
      return new Proxy(obj.value as unknown as T, {
        set(target, propertyName, newValue): boolean {
          o.value = { ...target, [propertyName]: newValue }

          return true
        },
      })
    },
    set: (newValue: T): void => {
      obj.value = newValue as unknown as S
    },
  })

  return o
}

The composable above is a simplified version of the final one that should handle also object properties in arrays, to
achieve this case the solution is to return a deep proxy, something like this:

export function useDeepModel<T extends object, M extends PropertyKey = string, G = T, S = T>(
  obj: ModelRef<T, M, G, S>,
): WritableComputedRef<T> {
  function createDeepProxy(target: T, update: (newValue: any) => void): T {
    return new Proxy(target, {
      get(target: T, p, receiver) {
        const value = Reflect.get(target, p, receiver)

        if (typeof value === 'object') {
          return createDeepProxy(value as T, (newChildValue: any) => {
            const targetCopy = Array.isArray(target) ? [...target] : { ...target }

            targetCopy[p] = newChildValue
            update(targetCopy)

            return newChildValue
          })
        }

        return value
      },
      set(target, p, newValue, receiver) {
        const targetCopy = Array.isArray(target) ? [...target] : { ...target }

        targetCopy[p] = newValue
        update(targetCopy)

        return Reflect.set(target, p, newValue, receiver)
      },
    })
  }

  const o = computed({
    get: (): T => {
      return createDeepProxy(obj.value as unknown as T, (newValue: T) => {
        o.value = newValue
      })
    },
    set: (newValue: T): void => {
      obj.value = newValue as unknown as S
    },
  })

  return o
}

Directive (v-deep-model)

The idea of this directive is that it should be a direct extension of
packages/runtime-dom/src/directives/vModel.ts,
meaning that it would reuse the code from each hook of the standard vModel as the vDeepModel should be used to still
update primitives with the difference that they are direct properties of an object, for this purpose I came up with
the following api to be used in the child:

Definitions:

Deep mutation: the update/mutation of a property of an object through a whole object update after that an event
has been emitted for that purpose.

Notations

Object notation

v-deep-model:arg="value"

Array notation

v-deep-model:arg="[objectToUpdate, indexKey]"

Notation differences and properties

• value is object|[object, number], in the first case we have the Object notation whose value is
  exactly the object to deeply update; in the second case we have the Array notation whose value[0] is the object
  contained in the array to update at a specific index being value[1] or the array to update at a specific index being value[1].
  In js arrays are considered objects so basically indexKey should be number|string|symbol, but I would restrict the type
  there to number just to have a neat distinction between objects and arrays to deeply mutate, so all the cases where
  Array.isArray(value[0]) === true.

• arg is always required and there can be multiple ones, separated by a column : and it always refers to one
  or additional child properties of value:
  v-deep-model:first-arg:second-arg="value" -> value.firstArg.secondArg will be updated.
  v-deep-model:second-arg="[value.first-arg, index]" -> value.firstArg[index].secondArg will be updated.
  v-deep-model:first-arg:second-arg="[value, index]" -> value.firstArg[index].secondArg will be updated.

• The Array notation is pretty useful when working with objects being elements of array properties, and it cannot contain
  more than 2 elements.

• The Object notation is a sub notation of the Array notation meaning that you can still replicate the same behaviour
  of the former through the latter but not viceversa.

Examples

const editablePerson = { 
    name: 'Michael', 
    address: { city: 'London' },
    children: [
        {
            name: 'Mark',
            address: { city: 'Manchester' },
            children: [],
        }
    ]
}

Object notation

1. v-deep-model:name="editablePerson": It means that the object editablePerson will be deeply mutated on the name property.

2. v-deep-model:address:city="editablePerson": It means that the object editablePerson will be deeply mutated on the address.city property,
   where address is an object and city its property.

3. v-deep-model:city="editablePerson.address": It is the same as 2 with the difference that the address object
   is the value instead of an argument.

Array notation

4. v-deep-model:name="[editablePerson]": It is the same as 1.

5. v-deep-model:children:name="[editablePerson, index]": It means that the object editablePerson will be
   deeply mutated on the children[index].name property.

6. v-deep-model:name="[editablePerson.children, index]": It is the same as 5.

Drawbacks

This feature obliges the user to use defineModel and implicitly, in case of (many) nested components, it might lead
to prop drilling. I still believe that having 3-5 nested components and manipulating the data this way is absolutely fine
and that amount of components would be the average used by the developers, and it's actually better than attempting to
mutate a deep reactive property of a prop object. Vue itself is suggesting the use of defineModel, so the usage of
the combination of defineModel and, useModel or v-deep-model, is perfectly acceptable.

Alternatives

At the moment the only alternatives are:

https://vueuse.org/core/useVModel/#usevmodel

https://vueuse.org/core/useVModels/#usevmodels

But they might be expensive in terms of resource usage as they use (deep) watchers.

Adoption strategy

It's a completely new feature that adds a new composable and a directive that is built on top of an existing one, so no
breaking change should be involved.

In case my proposal gets approved I'm up to implement it.

Unresolved questions

N/A

[sphex813]

Hi @michaelcozzolino, any news? why was this closed?

[michaelcozzolino]

I edited the post on top after attempting to implement some draft and explaining why it cannot be done, but maybe i am wrong and it is just out of my knowledge

[jaypeerj]

I was puzzling this over myself. The following would be pretty flexible but it'd need some modding by the vue js team

import { computed } from 'vue'
import cloneDeep from 'lodash/cloneDeep'
import get from 'lodash/get'
import set from 'lodash/set'

export const useDeepVModel = () => {
  /**
   * Computes a deep model for a given prop, where each node is a computed property.
   * @param props - The props object passed to the component.
   * @param propKey - The key of the prop to be deeply modeled.
   * @param emit - The emit function to trigger updates.
   * @param parentPath - The parent path (used for nested updates).
   * @returns An object with computed getters and setters for each level of depth.
   */
  const computeDeepModel = (props: Record<string, any>, propKey: string, emit: Function, parentPath: string | undefined = undefined) => {
    const rootObject = get(props, propKey, {})

    const createComputedNode = (path: string): any => {
      const value = get(rootObject, path)

      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
        // If the value is an object, recursively create computed properties for its children
        return computed({
          get: () => {
            const currentValue = get(props[propKey], path)
            return Object.entries(currentValue || {}).reduce((obj, [ key, _ ]) => {
              // @ts-ignore
              obj[key] = createComputedNode(`${path}.${key}`)
              return obj
            }, {})
          },
          set: (newValue: any) => {
            const updatedObject = cloneDeep(props[propKey])
            set(updatedObject, path, newValue)
            emit(`update:${propKey}`, updatedObject)
          },
        })
      } else {
        // Create computed properties for primitive values
        return computed({
          get: () => get(props[propKey], path),
          set: (newValue) => {
            const updatedObject = cloneDeep(props[propKey])
            set(updatedObject, path, newValue)
            emit(`update:${propKey}`, updatedObject)
          },
        })
      }
    }

    // Start creating the computed model from the root object
    return Object.entries(rootObject).reduce((obj, [ key ]) => {
      const fullPath = parentPath ? `${parentPath}.${key}` : key
      obj[key] = createComputedNode(fullPath)
      return obj
    }, {} as Record<string, any>)
  }

  return {
    computeDeepModel,
  }
}

the problems you're gonna have are:

1. you have computeds in computeds. Not sure that's great behavior. But - as I say - there's probably a lower level solution to this if the vue team took it on.
2. because it uses computeds in computeds you have to do some pretty odd stuff. see the click event in the button below:

<template>
  <div>
    <Button @click="d_item.foo.value.bah.value.baz.value.test.value = 'test 2'">
      WHAT HAPPENS
    </Button>
  </div>
</template>

<script setup>
const { computeDeepModel } = useDeepVModel()

const props = defineProps({
  item: {
    type: Object,
    default: () => ({}),
  },
})

const emit = defineEmits([ 'update:item' ])

const d_item = computeDeepModel(props, 'item', emit)
</script>

my tests indicate that this does emit to update:item correctly. but as you can see: you have to slap .value on to every node. Effectively, there'd need to be a low level way of writing a computedReactive<> or somesuch that meant you could mitigate this issue.

so that's my 2 pence :)

[michaelcozzolino]

Which vue version are you talking about? There is also a pinia branch for vue2 or you can even use vuex probably

[jaypeerj]

whichever. Pinia/Vuex/composable/redux. If you have a maintained private commercial repo with plug and play components that take objects, say.

I've written this, see what you think :)

#790

[michaelcozzolino]

well the problem is not about having props as object, but props as object that must be modified through nested components, your rfc is basically the same as this one, the only difference is that i was using a ModelRef in the composable and you seem to be using just an object and emitting the events manually. I don't know now you codebase environment, but if you are unable to use vuex/pinia I would suggest you refactoring/updating the code to use newer versions or to try using provide/inject. they both can solve this problem of props modification in object properties. I have been using object many times and the change from the composable (useDeepModel) to pinia or provide/inject gave me exactly the same results

[jaypeerj]

again, provide/inject assumes extra dependencies. in a private repo where, ideally, you don't want to rely on the client using provide, that isn't an option. Refactor would be great but isn't always an option with large old projects that haven't been well implemented (in my case, I'm at the mercy of an inherited codebase)

[jaypeerj]

I've made some modifications as there was an edge case. here's a stackblitz