Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 87 ยท Reactivity Fundamentals

reactive Objects

Learn Vue 3 reactive(): how proxy-based reactivity works, its limitations with destructuring and replacement, when to choose ref or reactive, and toRef/toRefs.

ref() wraps one value in a container. Vue has a second way to create reactive state, reactive(), which makes an object itself reactive, so you read and write its properties directly, without .value. For state that is naturally a bundle of related fields (a form, a settings object) this can read more naturally.

The trade-off is that reactive() has sharp edges you need to know about. This lesson explains how it works, where it breaks, and how to choose between the two.

Creating a reactive object

reactive() takes an object and returns a reactive version of it:

A reactive object used directly

There is no .value anywhere: form.age++ just works, in script and in the template. Reactivity is deep, so the nested array tags is tracked as well.

How it works: proxies

reactive() returns a JavaScript Proxy around your object. A proxy intercepts operations such as reading a property (get) and assigning one (set). Vue records which code read which property during rendering, and re-runs that code when the property is later set.

flowchart LR
  C["Your code<br/>state.count++"] --> P["Proxy (reactive)"]
  P -- "get: track the reader" --> O["Original object"]
  P -- "set: trigger dependents" --> O
  P --> E["Re-render"]

A proxy sits between your code and the object, spying on reads (tracking) and writes (triggering).

The proxy is a different object from the original, and only the proxy is reactive:

The proxy is not the original

The first two lines print false and true. Clicking "Via raw" changes the data but not the screen; the next time something else re-renders (or you press "Read value now") the new number appears. The lesson: always use the proxy, and keep the raw object out of reach, ideally by never naming it.

Limitations of reactive()

Because reactive() works by tracking property access on one specific proxy object, a few things lose reactivity.

1. Only objects work. It accepts objects, arrays, Map and Set, but not primitives (string, number, boolean). That is one of the reasons ref exists.

2. You cannot replace the object. The connection is to the proxy object. If you reassign the variable, everything holding the old proxy keeps pointing at the old data:

JavaScript
let state = reactive({ count: 0 });
state = reactive({ count: 1 }); // the template still uses the old proxy

The fix is to mutate the existing object (state.count = 1, or Object.assign(state, { count: 1 })), or wrap it in a ref when you need replacement.

3. Destructuring breaks the link. Pulling a property out copies its current value into a plain variable:

Destructuring loses reactivity

After clicking, state.count and the toRef line go up, while the destructured copy stays at 0. The same thing happens when you pass state.count (a number) to a function: the function gets a value, not a connection.

toRef and toRefs

toRef(object, "key") creates a ref linked to one property of a reactive object: reading and writing the ref reads and writes the property. toRefs(object) does that for every property at once, returning a plain object of refs. Destructuring that is safe:

toRefs for safe destructuring

Typing in either input updates the displayed name and the JSON of the original object, because each ref reads and writes the matching property. toRefs is particularly useful when a composable returns a reactive object and callers want to destructure it. (The JSON.stringify call is a global the template allows; see Text Interpolation.)

ref or reactive?

Both are fully supported. The Vue team's practical advice is to use ref() as your default and reactive() when you have a fixed group of related fields that you never replace as a whole. Reasons:

Question ref() reactive()
Holds primitives Yes No
Replace the whole value Yes (x.value = ...) No, mutate instead
Safe to destructure The ref itself is a stable handle No, use toRefs
Needs .value in script Yes No
Safe to pass to functions Yes, keeps the connection Yes, as the whole object only

A common style is ref for single values and reactive for one form-state object. Another is ref for everything, so the rule is the same everywhere. Choose one convention per project and apply it consistently. A reactive object also unwraps refs stored inside it: if state.count holds a ref, state.count reads the number. Refs inside reactive arrays and Maps are not unwrapped, which is a known edge case.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does reactive() return?

    reactive() wraps the original in a Proxy that tracks reads and triggers on writes. The original object is not itself reactive.
  2. 2. Which line breaks reactivity?

    Destructuring copies the current primitive value into a plain variable that no longer knows about the proxy.
  3. 3. Why can you not write state = reactive({ ... }) to replace a reactive state?

    Reactivity is attached to the proxy object, not to your variable name. Mutate the existing object or use a ref.
  4. 4. What does toRefs(state) give you?

    Each property becomes a ref that stays in sync with the matching property, so destructuring the result is safe.
  5. 5. Which type can you NOT pass to reactive()?

    reactive() works on object types only. For a number, string or boolean, use ref().

Summary

  • reactive(obj) returns a deep proxy; you use its properties directly, with no .value.
  • Reads are tracked and writes trigger updates; always work through the proxy, not the raw object.
  • It only accepts objects, cannot be replaced wholesale, and loses reactivity when you destructure or pass a property's primitive value.
  • toRef links one property to a ref; toRefs does it for all properties so you can destructure safely.
  • Default to ref, and use reactive for a fixed bundle of fields you mutate in place.

Next, derive values from your state with Computed Properties.