Vue 3 변수 정의 완전 정복 – ref, reactive, toRef, toRefs 언제 어떻게 쓸까?

Vue 3에서는 ref, reactive, toRef, toRefs 등 다양한 방식으로 변수를 선언한다.
이름도 비슷하고 용도도 겹쳐 보이지만, 구조와 목적을 정확히 이해하면 상황에 맞게 효율적으로 사용할 수 있다.
이 글에서는 각 방식의 차이점과 실전 사용법, 그리고 상황별 추천까지 한 번에 정리한다.

---

✅ 변수 선언 방식 비교

방식	대상	.value 필요	구조분해 가능	사용 예시	추천 상황
🧩 ref	원시값, DOM 참조	✅ 필요	❌ 불가	const count = ref(0)	단일 숫자, 문자열, 불린 값 관리에 적합
🧱 reactive	객체, 배열	❌ 불필요	❌ 직접 불가	const state = reactive({ a: 1 })	여러 속성을 가진 복합 객체 전체 상태 관리에 적합
🎯 toRef	reactive 객체의 속성	✅ 필요	✅ 가능	const title = toRef(state, 'title')	특정 속성만 독립적으로 ref처럼 다뤄야 할 때
🧷 toRefs	reactive 객체 전체	✅ 필요	✅ 가능	const { a, b } = toRefs(state)	구조분해하면서도 반응형 유지가 필요한 경우

---

✅ 사용법

ref – 단일 상태값을 다룰 때 사용한다.

ref는 숫자, 문자열, 불린과 같은 원시값을 반응형으로 만들 때 사용한다.
.value를 통해 접근하며, 가장 기본적인 상태 저장 방법이다.

import { ref } from 'vue'

const count = ref(0)
count.value++

reactive – 객체 전체를 반응형으로 관리할 때 사용한다.

reactive는 객체나 배열 전체를 반응형으로 만들고 싶을 때 사용한다.
.value 없이 속성에 직접 접근할 수 있고, 구조가 있는 데이터를 다루기에 적합하다.
import { reactive } from 'vue'

const user = reactive({
  id: null,
  name: '',
  email: ''
})

user.name = 'Alice'

toRef – 객체의 특정 속성만 분리해서 다뤄야 할 때 사용한다.

toRef는 reactive 객체에서 특정 속성 하나만 ref처럼 따로 뽑아 사용할 수 있게 한다.
이 방식은 해당 속성을 개별로 넘겨야 하거나, watch나 props로 연결할 때 유용하다.

import { reactive, toRef } from 'vue'

const user = reactive({ name: 'Vue' })
const name = toRef(user, 'name')

name.value = 'React'  // user.name 도 함께 바뀜

toRefs – 구조분해하면서도 반응형을 유지하고 싶을 때 사용한다.

toRefs는 reactive 객체를 구조분해할 때 반응형 연결을 유지해준다.
템플릿에서 개별 속성처럼 사용할 수 있어 컴포넌트 가독성이 좋아진다.

import { reactive, toRefs } from 'vue'

const user = reactive({ name: 'Vue', age: 3 })
const { name, age } = toRefs(user)

name.value = 'Nuxt'