Vue 3 Reactivity Composition API – using reactive() and ref()

Reactivity is a key pillar for building VueJS applications. While VueJS Reactivity using Options API is quite powerful, more and more developers are moving to Composition API for building their Vue applications. Thankfully, Vue 3 Reactivity with Composition API is equally robust.

Vue 3 Reactivity with Composition API is driven by reactive() and ref() functions. These functions turn the component model data reactive so that Vue is able to track changes. However, both reactive() and ref() have their specific use-cases. It is important to know which function should be used in which particular scenario.

In this post, we will look at reactivity in Vue 3 Composition API for a Single File Component or SFC. In case you are new to these terms, check out this post on Vue 3 Options API vs Composition API.

1 – Vue 3 reactive() Function

The reactive() function in VueJS helps create a piece of reactive state.

import { reactive} from 'vue'

// reactive state
const state = reactive({
  currentCounterStatus: '',
})

Vue is able to track mutations of any property within the reactive object. In the above example, if the value of currentCounterStatus changes, VueJS will automatically update the DOM.

We can use the reactive state variable within the template by using template syntax.

<template>
  <h2>{{ state.currentCounterStatus }}</h2>
</template>

The value of reactive state can be updated as below:

function increment() {
  state.currentCounterStatus = 'Incremented'
}

We can trigger the increment() function using any click handler.

The reactive() API has some limitations as below:

• We can use reactive() API to only declare objects, arrays or other collection types such as Map or Set. Basically, reactive() function does not work for primitives such as string, integer, boolean etc. In my view, this is a big disadvantage that limits the use of reactive() API.
• We must always keep the same reference to the reactive object. In other words, if we update the value of a reactive object by again calling reactive() function, the reactivity connection to the first object is lost. See below example:

import { reactive} from 'vue'

// reactive state
let state = reactive({
  currentCounterStatus: '',
})

state = reactive({
  currentCounterStatus: 'Incremented'
})

2 – Vue 3 Reactivity using ref() Function

Vue 3 also provides the ref() function to declare reactive state. Basically, the ref() function solves the limitations with the reactive() function. Mainly, ref() can hold any type of value including primitives.

See below example:

import {ref } from 'vue'

const appName = ref('Counter Application')
const counter = ref(0)

function increment() {
  counter.value++
}

Basically, ref() takes the input argument and wraps it within an object. This object has a value property. In other words, for the above example, we can access appName variable as appName.value. Also, counter value can be accessed as counter.value.

2.1 – Vue 3 Ref Unwrapping in Templates

We can also access reactive variables from ref() function within the template.

See below example:

<template>
  <h1>{{ appName }}</h1>
  <h2>Count is: {{ counter }}</h2>
</template>

As you can see, here we don’t need to use counter.value or appName.value. Basically, when we access refs as top-level properties in the template, VueJS automatically unwraps them. Therefore, no need to use .value.

Important point is that ref unwrapping works only for top-level properties. It won’t work for an example as below:

const counterStatusObject = {
  status: ref(''),
}

This is because counterStatusObject.status is a Javascript object.

2.2 – Vue 3 Ref Unwrapping in Reactive Objects

We can also add a ref variable as property of a reactive object. See below:

const appName = ref('Counter Application')
const appObject = reactive({
   appName
})

console.log(appObject.appName)

In this case, we can directly access appName without the .value.

2.3 – Vue 3 Reactivity Transform

You might feel that using .value is unnecessarily cumbersome. It reduces the simplicity of accessing variables in a template.

Vue 3 provides compile-time transform that can get around this issue. We can now use $ref() to declare a reactive variable and directly access it without .value.

const appName = $ref('Counter Application')
const counter = $ref(0)

function increment() {
  counter++
}

However, do note that this is still an experimental feature and prone to changes.

Conclusion

In this post, we covered Vue 3 Reactivity using Composition API. As part of this, we look at the reactive() and ref() functions available with Vue that help us declare reactive objects and variables.

You can play around with the complete code on Stackblitz.

Are you planning to have complicated computations in your VueJS templates? Check out this post on using computed properties in Vue 3.

If you have any comments or queries about this post, please feel free to mention them in the comments section below.