Crear variables reactivas en Composition API de Vue.js cambia la forma en que defines el estado dentro de un componente. En lugar de declarar datos en la opción data, ahora trabajas con funciones como ref y reactive dentro de setup, lo que te da más control y te permite escribir lógica con JavaScript puro sin perder la reactividad.

Esta guía es para ti si vienes de Options API y quieres entender cómo declarar valores que se actualizan solos en la vista cuando cambian en el código.

Cómo se declara una variable reactiva con ref en Vue

La función ref crea una referencia reactiva a un dato. La importas directamente desde Vue y la usas dentro de setup para envolver el valor que quieres observar.

js import { ref } from 'vue'

export default { setup() { const text = ref('Hola, Vue') const counter = ref(0)

setInterval(() => {
  counter.value++
}, 500)

return { text, counter }

} }

Fíjate en dos detalles que marcan toda la diferencia:

• Para leer o reasignar el valor dentro de setup, siempre usas .value.
• En el template no necesitas .value; Vue lo resuelve automáticamente.
• Para que la variable esté disponible en el template, la incluyes en el return de setup.

¿Qué hace ref en Vue 3? Crea una referencia reactiva a un valor primitivo como un número, string o booleano. Accedes a ese valor con .value dentro del script y directamente por su nombre en el template.

Por qué necesitas usar .value con ref

Cuando envuelves un valor con ref, Vue devuelve un objeto contenedor. Ese contenedor expone la propiedad value, que es la que el sistema de reactividad observa.

Si intentas reasignar la variable sin .value, rompes la referencia y Vue deja de detectar el cambio. Por eso la convención es estricta: dentro del script, siempre .value.

El ejemplo del setInterval lo deja claro. Cada 500 milisegundos se ejecuta counter.value++ y la vista se actualiza sola, sin necesidad de un hook mounted ni de declarar el dato en data. Es JavaScript plano apoyado por la reactividad de Vue.

Cuándo usar reactive en lugar de ref

ref funciona perfecto para tipos primitivos, pero cuando trabajas con objetos conviene usar reactive. Esta función toma un objeto completo y lo convierte en reactivo, sin obligarte a usar .value en cada propiedad.

js import { reactive } from 'vue'

export default { setup() { const obj = reactive({ counter: 0 })

setInterval(() => {
  obj.counter++
}, 500)

return { obj }

} }

La diferencia práctica es esta:

• Con ref, accedes con variable.value.
• Con reactive, accedes con objeto.propiedad.
• En el template, ambos se usan sin sintaxis adicional.

¿Cuál es la diferencia entre ref y reactive? ref envuelve valores primitivos como strings, números o booleanos y requiere .value. reactive envuelve objetos y permite acceder a sus propiedades de forma directa.

Qué pasa si usas ref con un objeto

En la clase ocurre justo eso: al envolver un objeto con ref, aparece un error al intentar leer la propiedad. La solución es cambiar a reactive, que está pensado para estructuras complejas. Esa es la regla práctica que conviene memorizar.

Cómo expone setup las variables al template

El puente entre la lógica y la vista es el return de la función setup. Todo lo que devuelvas en ese objeto queda disponible en el template del componente.

Esto reemplaza el comportamiento que antes lograbas con data, y te da una ventaja extra: dentro de setup puedes mezclar declaraciones, llamadas a funciones, setInterval, condicionales y cualquier construcción de Vanilla JavaScript. La reactividad sigue funcionando mientras respetes la convención de .value en los ref.

¿Necesito devolver las variables en setup? Sí. Solo lo que retornas desde setup está disponible en el template. Si no lo incluyes en el return, Vue no puede renderizarlo.

Un punto importante: si declaras una variable normal sin ref ni reactive, Vue no la observa. Aunque cambie su valor en memoria, la vista nunca se va a actualizar. Esa conciencia de qué es reactivo y qué no es lo que te da control real sobre el componente.

Con estas dos funciones ya tienes la base para construir cualquier estado dentro de Composition API. ¿Cuál crees que vas a usar más en tus componentes, ref o reactive? Cuéntame en los comentarios cómo lo estás aplicando en tu proyecto.