shallowRef() Shallow Reactive Ref
Last updated: 2026-10-22
shallowRef() Shallow Reactive Ref
shallowRef() only tracks replacement of .value — swapping the whole value updates, mutating inner properties does not.
| Group | Reactivity: Advanced |
|---|---|
| Kind | API |
| Scope | Component |
| Vue Version | 3.0+ |
| SSR Support | Yes |
📝 Syntax
const big = shallowRef({ list: [] })
big.value = { list: [1] } // ✅ triggers
big.value.list.push(2) // ❌ no trigger (inner not proxied)⚙️ Arguments
| value | Any initial value (no deep proxying inside) |
|---|
Returns：A shallow ref object
▶ Example
Edit the code below and see the live result:
Output：
Pushing inside leaves the number unchanged; replacing the whole value shows 3.💡 Key Points
💡 Tip Great for big datasets, third-party instances and chart/map objects replaced wholesale.
⚠️ Warning Use triggerRef to force an update after inner mutation, though replacing wholesale is cleaner.
ℹ️ Note isShallow() detects shallow refs.
🏷️ Related Advanced
💡 Related Cases
More case studies coming soon.
📚 Related Tutorials
❓ FAQ
Q When is shallowRef necessary?
A When wrapping large read-mostly structures you replace as a whole.
Q Why does the page not update after push?
A Inner objects are not proxied, so the change is invisible; replacing .value notifies.
Q Is the perf gap big?
A Significant for deep large objects; negligible for small ones.
