toRef() Turn a Property into a Linked Ref
Last updated: 2026-10-22
toRef() Turn a Property into a Linked Ref
toRef() converts one property of a reactive object into a ref that stays linked — reading or writing it touches the original property.
| Group | Reactivity: Utilities |
|---|---|
| Kind | API |
| Scope | Component |
| Vue Version | 3.0+ |
| SSR Support | Yes |
📝 Syntax
const state = reactive({ count: 0 })
const count = toRef(state, 'count')
count.value++ // same as state.count++⚙️ Arguments
| object | A reactive object |
|---|---|
| key | The property name |
Returns：A ref linked to the original property
▶ Example
Edit the code below and see the live result:
Output：
Both numbers always match: writing the ref updates state.count.💡 Key Points
💡 Tip Standard use: convert a prop field into a ref before passing it to a composable.
ℹ️ Note toRef(state, 'a') equals toRefs(state).a; missing keys still work (writable).
⚠️ Warning It is a channel, not a copy — replacing the source object breaks the link.
🏷️ Related Utilities
💡 Related Cases
More case studies coming soon.
📚 Related Tutorials
❓ FAQ
Q toRef vs toRefs?
A toRef handles one property; toRefs returns a ref per property for whole-object destructuring.
Q Why not just destructure?
A Plain destructuring copies a snapshot; toRef keeps the live link.
Q Does it work on plain objects?
A Yes, though a plain object carries no reactivity — the ref is just an accessor.
