Home Arrow Icon Knowledge base Arrow Icon Global Arrow Icon how does the auto-unwrapping feature in Vue templates work with ref() and reactive()
    Vue.js ref() reactive() auto-unwrapping Vue templates Vue reactivity JavaScript frameworks Vue.js tutorial


how does the auto-unwrapping feature in Vue templates work with ref() and reactive()


The auto-unwrapping feature in Vue templates works differently for `ref()` and `reactive()`:

`ref()`

- Auto-unwrapping: When you use `ref()` to create a reactive reference to a primitive value (e.g., a string, number, or boolean), Vue automatically unwraps the ref in templates. This means that when you access the ref in a template, you don't need to use the `.value` property. For example:

javascript
  import { ref } from 'vue';

  const count = ref(0);

  <template>
    <div>{{ count }}</div>
  </template>
  

In this case, `count` is automatically unwrapped and the value `0` is displayed in the template.

- No auto-unwrapping for nested refs: When you use `ref()` to create a reactive reference to a nested object or array, Vue does not automatically unwrap the nested refs. You need to use the `.value` property to access the nested values. For example:

javascript
  import { ref } from 'vue';

  const user = ref({
    name: 'Michael Scott',
    address: {
      street: '123 Main St',
      city: 'Scranton',
      state: 'PA',
      zip: '12345'
    }
  });

  <template>
    <div>{{ user.value.name }}</div>
    <div>{{ user.value.address.street }}</div>
  </template>
  

Here, `user.value` is unwrapped, but `user.value.address` is not. You need to use `.value` to access the nested values.

`reactive()`

- No auto-unwrapping: When you use `reactive()` to create a reactive object, Vue does not automatically unwrap the object in templates. You need to use the object properties directly without the `.value` property. For example:

javascript
  import { reactive } from 'vue';

  const user = reactive({
    name: 'Michael Scott',
    address: {
      street: '123 Main St',
      city: 'Scranton',
      state: 'PA',
      zip: '12345'
    }
  });

  <template>
    <div>{{ user.name }}</div>
    <div>{{ user.address.street }}</div>
  </template>
  

Here, `user.name` and `user.address.street` are accessed directly without needing `.value`.

- No auto-unwrapping for nested reactive objects: When you use `reactive()` to create a reactive object with nested objects or arrays, Vue does not automatically unwrap the nested objects. You need to use the object properties directly without the `.value` property. For example:

javascript
  import { reactive } from 'vue';

  const user = reactive({
    name: 'Michael Scott',
    address: reactive({
      street: '123 Main St',
      city: 'Scranton',
      state: 'PA',
      zip: '12345'
    })
  });

  <template>
    <div>{{ user.name }}</div>
    <div>{{ user.address.street }}</div>
  </template>
  

Here, `user.name` and `user.address.street` are accessed directly without needing `.value`.

In summary, `ref()` automatically unwraps primitive values but not nested refs, while `reactive()` does not auto-unwrap any values.

Citations:
[1] https://github.com/vuejs/core/issues/737
[2] https://stackoverflow.com/questions/77539774/i-dont-understand-ref-unwrapping-in-the-template-using-typescript
[3] https://michaelnthiessen.com/ref-vs-reactive
[4] https://github.com/vuejs/rfcs/issues/533
[5] https://vuejs.org/guide/essentials/reactivity-fundamentals