Reactivity Fundamentals

We can create a reactive object or array with the reactive() function:

import { reactive } from 'vue'

const state = reactive({ count: 0 })

Reactive objects are JavaScript Proxies and behave just like normal objects. The difference is that Vue is able to track the property access and mutations of a reactive object. If you are curious about the details, we explain how Vue's reactivity system works in Reactivity in Depth - but we recommend reading it after you have finished the main guide.

See also: Typing Reactive

To use reactive state in a component's template, declare and return them from a component's setup() function:

import { reactive } from 'vue'

export default {
  // `setup` is a special hook dedicated for composition API.
  setup() {
    const state = reactive({ count: 0 })

    // expose the state to the template
    return {
      state
    }
  }
}

<div>{{ state.count }}</div>

Similarly, we can declare functions that mutate reactive state in the same scope, and expose it as a method alongside the state:

import { reactive } from 'vue'

export default {
  setup() {
    const state = reactive({ count: 0 })

    function increment() {
      state.count++
    }

    // don't forget to expose the function as well.
    return {
      state,
      increment
    }
  }
}

Exposed methods are typically used as event listeners:

<button @click="increment">
  {{ state.count }}
</button>

<script setup>

Manually exposing state and methods via setup() can be verbose. Luckily, it is only necessary when not using a build step. When using Single-File Components (SFCs), we can greatly simplify the usage with <script setup>:

<script setup>
import { reactive } from 'vue'

const state = reactive({ count: 0 })

function increment() {
  state.count++
}
</script>

<template>
  <button @click="increment">
    {{ state.count }}
  </button>
</template>

Try it in the Playground

Top-level imports and variables declared in <script setup> are automatically usable in the template of the same component.

For the rest of the guide, we will be primarily using SFC + <script setup> syntax for Composition API code examples, as that is the most common usage for Vue developers.

Reactive Proxy vs. Original

It is important to note that the returned value from reactive() is a Proxy of the original object, which is not equal to the original object:

const raw = {}
const proxy = reactive(raw)

// proxy is NOT equal to the original.
console.log(proxy === raw) // false

Only the proxy is reactive - mutating the original object will not trigger updates. Therefore, the best practice when working with Vue's reactivity system is to exclusively use the proxied versions of your state.

To ensure consistent access to the proxy, calling reactive() on the same object always returns the same proxy, and calling reactive() on an existing proxy also returns that same proxy:

// calling reactive() on the same object returns the same proxy
console.log(reactive(raw) === proxy) // true

// calling reactive() on a proxy returns itself
console.log(reactive(proxy) === proxy) // true

This rule applies to nested objects as well. Due to deep reactivity, nested objects inside a reactive object are also proxies:

const proxy = reactive({})

const raw = {}
proxy.nested = raw

console.log(proxy.nested === raw) // false

Limitations of reactive()

The reactive() API has two limitations:

1. It only works for object types (objects, arrays, and collection types such as Map and Set). It cannot hold primitive types such as string, number or boolean.

2. Since Vue's reactivity tracking works over property access, we must always keep the same reference to the reactive object. This means we can't easily "replace" a reactive object:

   let state = reactive({ count: 0 })
   
   // this won't work!
   state = reactive({ count: 1 })

   It also means that when we assign or destructure a reactive object's property into local variables, or when we pass that property into a function, or destructure properties from a reactive object, we will lose the reactivity connection:

   const state = reactive({ count: 0 })
   
   // n is a local variable that is disconnected
   // from state.count.
   let n = state.count
   // does not affect original state
   n++
   
   // count is also disconnected from state.count.
   let { count } = state
   // does not affect original state
   count++
   
   // the function receives a plain number and
   // won't be able to track changes to state.count
   callSomeFunction(state.count)

Reactive Variables with ref()

To address the limitations of reactive(), Vue also provides a ref() function which allows us to create reactive "refs" that can hold any value type:

import { ref } from 'vue'

const count = ref(0)

ref() takes the argument and returns it wrapped within a ref object with a .value property:

const count = ref(0)

console.log(count) // { value: 0 }
console.log(count.value) // 0

count.value++
console.log(count.value) // 1

See also: Typing Refs

Similar to properties on a reactive object, the .value property of a ref is reactive. In addition, when holding object types, ref automatically converts its .value with reactive().

A ref containing an object value can reactively replace the entire object:

const objectRef = ref({ count: 0 })

// this works reactively
objectRef.value = { count: 1 }

Refs can also be passed into functions or destructured from plain objects without losing reactivity:

const obj = {
  foo: ref(1),
  bar: ref(2)
}

// the function receives a ref
// it needs to access the value via .value but it
// will retain the reactivity connection
callSomeFunction(obj.foo)

// still reactive
const { foo, bar } = obj

In other words, ref() allows us to create a "reference" to any value and pass it around without losing reactivity. This capability is quite important as it is frequently used when extracting logic into Composable Functions.

Ref Unwrapping in Templates

When refs are accessed as top-level properties in the template, they are automatically "unwrapped" so there is no need to use .value. Here's the previous counter example, using ref() instead:

<script setup>
import { ref } from 'vue'

const count = ref(0)

function increment() {
  count.value++
}
</script>

<template>
  <button @click="increment">
    {{ count }} <!-- no .value needed -->
  </button>
</template>

Try it in the Playground

Note the unwrapping only applies to top-level properties - nested access to refs will not be unwrapped:

const object = { foo: ref(1) }

{{ object.foo }} <!-- does NOT get unwrapped -->

We can fix that by making foo a top-level property:

const { foo } = object

{{ foo }} <!-- properly unwrapped -->

Now foo will be unwrapped as expected.

Ref Unwrapping in Reactive Objects

When a ref is accessed or mutated as a property of a reactive object, it is also automatically unwrapped so it behaves like a normal property:

const count = ref(0)
const state = reactive({
  count
})

console.log(state.count) // 0

state.count = 1
console.log(count.value) // 1

If a new ref is assigned to a property linked to an existing ref, it will replace the old ref:

const otherCount = ref(2)

state.count = otherCount
console.log(state.count) // 2
// original ref is now disconnected from state.count
console.log(count.value) // 1

Ref unwrapping only happens when nested inside a deep reactive object. It does not apply when it is accessed as a property of a shallow reactive object.

Ref Unwrapping in Arrays and Collections

Unlike reactive objects, there is no unwrapping performed when the ref is accessed as an element of a reactive array or a native collection type like Map:

const books = reactive([ref('Vue 3 Guide')])
// need .value here
console.log(books[0].value)

const map = reactive(new Map([['count', ref(0)]]))
// need .value here
console.log(map.get('count').value)

Reactivity Transform

Having to use .value with refs is a drawback imposed by the language constraints of JavaScript. However, with compile-time transforms we can improve the ergonomics by automatically appending .value in appropriate locations. Vue provides a compile-time transform that allows us to write the earlier "counter" example like this:

<script setup>
let count = $ref(0)

function increment() {
  // no need for .value
  count++
}
</script>

<template>
  <button @click="increment">{{ count }}</button>
</template>

You can learn more about Reactivity Transform in its dedicated section. Do note that it is currently still experimental and may change before being finalized.