Acceder a elementos del DOM en Vue 3 cambia cuando trabajas con Composition API. Los template refs te permiten obtener una referencia directa a un elemento HTML o componente desde el setup, pero la sintaxis y el momento en que ese valor está disponible son distintos a los que usabas con Options API. Aquí te explico cómo funcionan, por qué empiezan en null y cómo detectar el momento exacto en que el componente queda montado.

¿Qué son los template refs en Composition API?

Un template ref es una referencia reactiva a un elemento del template que puedes leer y manipular desde JavaScript. En Options API accedías con this.$refs.nombre dentro de un método, una propiedad computada o un hook del ciclo de vida. En Composition API ese this ya no existe dentro de setup, así que necesitas otra estrategia.

¿Por qué no puedo usar this.$refs en setup? Porque la función setup se ejecuta antes de que el componente se monte en el DOM. En ese momento no hay elementos renderizados ni un contexto this al que apuntar.

¿Cómo se declara un template ref con la función ref?

La convención es crear una variable reactiva usando la misma función ref que usas para estado, pero inicializada en null. Vue detecta que el atributo ref del template coincide con el nombre de tu variable y le asigna automáticamente el elemento HTML una vez montado.

Los pasos concretos son:

• Importar ref desde Vue.
• Declarar la variable dentro de setup, por ejemplo const btn = ref(null).
• Retornar la variable en el return para exponerla al template.
• Agregar el atributo ref="btn" al elemento HTML, como un <button>.

Con esto, Vue.js inyecta el nodo en btn.value justo cuando el componente termina de montarse.

¿Por qué el template ref empieza en null?

Si haces console.log(btn.value) directamente en setup, vas a ver null. No es un error: es el orden natural de ejecución. Primero corre setup, después Vue monta el DOM y solo entonces tu variable recibe el elemento real.

Para confirmarlo en vivo, puedes observar el cambio con un watcher. Importas watch desde Vue y vigilas la variable:

• Primer log: null, porque el componente todavía no está montado.
• Segundo log: el elemento HTML real, listo para manipularse con JavaScript.

Si olvidas importar watch, la consola te lanzará un watch is not defined. Es un detalle pequeño que conviene revisar antes de pelearte con el código.

¿Cuándo está disponible el valor real del ref? Después del montaje del componente. Por eso necesitas un watcher, un hook como onMounted, o cualquier callback que se ejecute tras la fase de render inicial.

¿Qué puedes hacer una vez que tienes el elemento?

Una vez que btn.value contiene el nodo del DOM, tienes acceso completo al elemento HTML. Puedes leer atributos, modificar estilos, escuchar eventos manualmente o integrarlo con librerías externas que necesiten un nodo real.

Algunos usos típicos:

• Enfocar un input automáticamente al cargar la vista.
• Medir dimensiones del elemento para cálculos de layout.
• Conectar librerías de terceros que esperan un nodo del DOM.
• Disparar animaciones imperativas sobre un botón o contenedor.

Es el mismo poder que tenías con this.$refs, pero ahora envuelto en una variable reactiva que puedes pasar a composables o vigilar con watch.

¿Por qué la función ref sirve para dos cosas distintas?

Aquí está lo interesante: la misma función ref que usas para crear estado reactivo (un número, un string, un objeto) también sirve para enlazar elementos del template. Esa unificación es intencional. Vue detecta el contexto: si el nombre coincide con un atributo ref en el template, asigna el nodo; si no, simplemente mantiene el valor reactivo que tú le des.

Por eso siempre accedes con .value, ya sea para leer un contador, un objeto de usuario o un <button> del DOM. La convención se mantiene y reduce la carga mental cuando saltas entre tipos de datos.

Cuéntame en los comentarios qué caso de uso tienes para los template refs en tu proyecto y si prefieres trabajarlos con watch o con onMounted.