What is useTemplateRef() (Vue 3.5) and how does it improve on ref=""?

Q: What is useTemplateRef() (Vue 3.5) and how does it improve on ref=""?

**Target Audience:** Vue developers who already use template refs and want to know what changed in 3.5. The general rules for refs (timing, `v-for`, component instances) are in [accessing a DOM element or child component instance](/interview-question/how-do-you-access-a-dom-element-or-child-component-instance). **Difficulty:** Medium > **How to read this doc:** Ideas are explained in plain language first, then tagged with 📌 Interview term: so you also learn the words an interviewer listens for. Every output in the "Verified" sections was produced on Vue 3.5.44: with the repo verifier (compiled and mounted in jsdom), with a harness that compiles the way the Vite dev server does, with a real vite build (Vite 8.3.4, @vitejs/plugin-vue 6.0.10) run in jsdom, and with vue-tsc 3.3.13 for types. ## 1. Why This Even Matters — A Story First A coat check at a theatre used to work like this: you hang your coat on hook number 14, and the attendant writes "

The problem

Question presented to candidate: "Vue 3.5 added useTemplateRef(). Before that we wrote const input = ref(null) and ref="input" in the template and it worked. What does useTemplateRef() actually fix, and would you migrate existing code to it?"

What a strong answer should cover:

useTemplateRef("key") returns a readonly shallow ref that Vue fills with the element or component whose ref attribute equals "key", matched by a runtime string, not by variable name.
The old pattern depended on the compiler matching a variable name to the attribute, which breaks for dynamic refs (:ref="activeKey"): it works against the dev server but stays null in a production build.
Because only a string is needed, a composable can own the template ref (useAutofocus("search")), and keys need not be valid JavaScript identifiers.
With Vue language tools, the type is inferred from the template: an element ref is typed as that element, a component ref as its exposed instance.
Behaviour details: it is null until mount, an array inside v-for, assigning to it is refused, and a second useTemplateRef with the same key warns.
Migration: new code should use it; old static refs keep working, but dynamic string refs and refs created inside composables are worth migrating first.

Clarifying questions expected:

"Are any of our refs dynamic, or created inside composables?"
"Are we on Vue 3.5 and current Vue language tools?"

Code / implementation expected: Yes — useTemplateRef in a component, ideally inside a small composable, and an example of a dynamic ref key.

usetemplateref
refs
vue-3.5

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Vue developers who already use template refs and want to know what changed in 3.5. The general rules for refs (timing, v-for, component instances) are in accessing a DOM element or child component instance. Difficulty: Medium

How to read this doc: Ideas are explained in plain language first, then tagged with 📌 Interview term: so you also learn the words an interviewer listens for. Every output in the "Verified" sections was produced on Vue 3.5.44: with the repo verifier (compiled and mounted in jsdom), with a harness that compiles the way the Vite dev server does, with a real vite build (Vite 8.3.4, @vitejs/plugin-vue 6.0.10) run in jsdom, and with vue-tsc 3.3.13 for types.

1. Why This Even Matters — A Story First

A coat check at a theatre used to work like this: you

The solution is hidden so you can try first

10 min read · 10 sections

Read the code

VueA composable that owns a template ref, plus a dynamic :ref key that swaps targets

Open in playground

<script setup>
import { ref, useTemplateRef, onMounted } from "vue";

// A composable can own a template ref: all it needs is the key string.
function useAutofocus(key) {
  const el = useTemplateRef(key);
  onMounted(() => el.value?.focus());
  return el;
}

const search = useAutofocus("search-box");   // the key does not have to be a valid JS name

// Dynamic refs: the key can change at runtime, and each useTemplateRef follows its own key.
const active = ref("first");
const first = useTemplateRef("first");
const second = useTemplateRef("second");
const report = ref("");

function swap() {
  active.value = active.value === "first" ? "second" : "first";
}
function check() {
  report.value =
    `focused search: ${document.activeElement === search.value} | ` +
    `first=${first.value?.tagName ?? null} second=${second.value?.tagName ?? null}`;
}
</script>

<template>
  <input ref="search-box" placeholder="search" />
  <input :ref="active" placeholder="dynamic ref" />
  <button class="swap" @click="swap">swap key</button>
  <button class="check" @click="check">check</button>
  <p>{{ report }}</p>
</template>

VueChild.vue and a typed parent: vue-tsc infers each ref from the template

<!-- Child.vue -->
<script setup lang="ts">
import { ref } from "vue";
const count = ref(0);
function reset() { count.value = 0; }
defineExpose({ reset });
</script>
<template><button @click="count++">{{ count }}</button></template>

<!-- Refs.vue: the parent, checked with vue-tsc -->
<script setup lang="ts">
import { ref, useTemplateRef, onMounted } from "vue";
import Child from "./Child.vue";

const auto = useTemplateRef("search");        // type inferred from the template
const child = useTemplateRef("child");
const manual = ref<HTMLInputElement | null>(null);

onMounted(() => {
  auto.value?.select();                 // fine: auto is HTMLInputElement
  auto.value?.notAMethod();             // error: not on HTMLInputElement
  child.value?.reset();                 // fine: reset is exposed
  child.value?.count;                   // error: count is not exposed
});
</script>
<template>
  <input ref="search" />
  <input ref="manual" />
  <Child ref="child" />
</template>

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.