How to Use shallowRef in Vue: Simple Guide with Examples

Use shallowRef in Vue to create a reactive reference that tracks changes only to the reference itself, not deeply inside its object value. This is useful when you want Vue to react only when the reference changes, not when nested properties change.

Syntax

The shallowRef function creates a reactive reference with shallow reactivity. It tracks changes only to the reference's value, not to nested properties inside objects or arrays.

Syntax parts:

• shallowRef(initialValue): Creates a shallow reactive reference holding initialValue.
• The returned object has a .value property to get or set the stored value.

javascript

import { shallowRef } from 'vue';

const myRef = shallowRef(initialValue);

// Access or update the value
console.log(myRef.value);
myRef.value = newValue;

Example

This example shows how shallowRef tracks changes only when the reference itself changes, not when nested properties change.

javascript

import { createApp, shallowRef } from 'vue';

const App = {
  setup() {
    const user = shallowRef({ name: 'Alice', age: 25 });

    function changeName() {
      // This will NOT trigger reactivity because nested property changed
      user.value.name = 'Bob';
    }

    function replaceUser() {
      // This WILL trigger reactivity because the whole object is replaced
      user.value = { name: 'Charlie', age: 30 };
    }

    return { user, changeName, replaceUser };
  },
  template: `
    <div>
      <p>User Name: {{ user.value.name }}</p>
      <p>User Age: {{ user.value.age }}</p>
      <button @click="changeName">Change Name (No Update)</button>
      <button @click="replaceUser">Replace User (Updates)</button>
    </div>
  `
};

createApp(App).mount('#app');

Output

<div>
  <p>User Name: Alice</p>
  <p>User Age: 25</p>
  <button>Change Name (No Update)</button>
  <button>Replace User (Updates)</button>
</div>

Common Pitfalls

Common mistakes when using shallowRef include expecting nested property changes to trigger updates, which they do not. Also, confusing ref and shallowRef can cause bugs.

Use ref if you want deep reactivity on nested properties. Use shallowRef when you want to optimize performance by tracking only the reference itself.

javascript

import { shallowRef } from 'vue';

const data = shallowRef({ count: 0 });

// Wrong: This will NOT trigger updates
 data.value.count++;

// Right: Replace the whole object to trigger updates
 data.value = { count: data.value.count + 1 };

Quick Reference

Feature	shallowRef	ref
Reactivity Depth	Shallow (only top-level value)	Deep (nested properties)
Use Case	Optimize performance, track only reference changes	Track all nested changes
Access Value	via .value	via .value
Trigger Update	Only when .value changes	When .value or nested properties change

Key Takeaways

Use shallowRef to create reactive references that track only the top-level value changes.

Nested property changes inside shallowRef do not trigger reactivity updates.

Replace the whole object in shallowRef to trigger updates.

Use ref instead of shallowRef if you need deep reactivity on nested properties.

shallowRef helps improve performance by avoiding deep reactivity overhead.