1---
2title: Use useTemplateRef for Template Refs in Vue 3.5+
3impact: MEDIUM
4impactDescription: Legacy ref pattern is error-prone due to name matching requirement
5type: best-practice
6tags: [vue3, vue35, template-refs, useTemplateRef, composition-api]
7---
8 
9# Use useTemplateRef for Template Refs in Vue 3.5+
10 
11**Impact: MEDIUM** - Before Vue 3.5, template refs required declaring a `ref()` with a name exactly matching the template's ref attribute. This fragile connection breaks silently during refactoring. Vue 3.5's `useTemplateRef()` eliminates this issue with explicit binding and better TypeScript support.
12 
13The legacy pattern causes no errors or warnings when names don't match - the ref simply stays null, leading to confusing debugging sessions.
14 
15## Task Checklist
16 
17- [ ] Use `useTemplateRef('ref-name')` in Vue 3.5+ projects
18- [ ] The first argument must exactly match the ref attribute value in the template
19- [ ] IDE support provides auto-completion for available ref names
20- [ ] TypeScript automatically infers the element type
21 
22**Incorrect (Legacy Pattern):**
23```vue
24<script setup>
25import { ref, onMounted } from 'vue'
26 
27// FRAGILE: Variable name MUST match template ref value exactly
28const input = ref(null)
29 
30// DANGER: After refactoring, names may not match
31const inputElement = ref(null) // Renamed variable...
32 
33onMounted(() => {
34  // NO ERROR - just silently null!
35  inputElement.value?.focus() // Does nothing
36})
37</script>
38 
39<template>
40  <!-- But template still uses old name -->
41  <input ref="input" />
42</template>
43```
44 
45```vue
46<script setup>
47import { ref } from 'vue'
48 
49// TYPO: 'inupt' instead of 'input' - no warning!
50const inupt = ref(null)
51</script>
52 
53<template>
54  <input ref="input" />
55  <!-- inupt.value will always be null -->
56</template>
57```
58 
59**Correct (Vue 3.5+):**
60```vue
61<script setup>
62import { useTemplateRef, onMounted } from 'vue'
63 
64// CORRECT: Explicit binding - argument matches template ref
65const inputElement = useTemplateRef('my-input')
66 
67onMounted(() => {
68  inputElement.value?.focus()
69})
70</script>
71 
72<template>
73  <!-- ref name is explicitly connected via useTemplateRef argument -->
74  <input ref="my-input" />
75</template>
76```
77 
78```vue
79<script setup>
80import { useTemplateRef, onMounted } from 'vue'
81 
82// BENEFITS:
83// 1. Variable name is independent of ref attribute
84// 2. IDE auto-completes available ref names
85// 3. TypeScript infers correct element type
86// 4. Typos in argument cause visible errors
87 
88const searchInput = useTemplateRef('search-box')
89const submitButton = useTemplateRef('submit-btn')
90 
91onMounted(() => {
92  // TypeScript knows these are HTMLInputElement and HTMLButtonElement
93  searchInput.value?.focus()
94  submitButton.value?.disabled = false
95})
96</script>
97 
98<template>
99  <input ref="search-box" type="search" />
100  <button ref="submit-btn">Submit</button>
101</template>
102```
103 
104## Limitation: v-for Refs
105 
106`useTemplateRef()` does **NOT** work with `v-for` refs. You must use the legacy `ref()` pattern for collecting multiple element references in a loop.
107 
108```vue
109<script setup>
110import { ref, onMounted } from 'vue'
111 
112// CORRECT: Legacy pattern required for v-for refs
113const itemRefs = ref([])
114 
115onMounted(() => {
116  // itemRefs.value is an array of DOM elements
117  itemRefs.value.forEach(el => {
118    console.log(el.textContent)
119  })
120})
121</script>
122 
123<template>
124  <ul>
125    <li v-for="item in items" ref="itemRefs" :key="item.id">
126      {{ item.text }}
127    </li>
128  </ul>
129</template>
130```
131 
132**Why this limitation exists:** When using `v-for`, Vue populates the ref with an array of elements. The `useTemplateRef()` API was designed for single element references and does not support the array population mechanism that `v-for` requires.
133 
134## Migration Guide
135 
136```vue
137<!-- BEFORE (Vue < 3.5) -->
138<script setup>
139import { ref } from 'vue'
140const myElement = ref(null) // Name must match template
141</script>
142<template>
143  <div ref="myElement"></div>
144</template>
145 
146<!-- AFTER (Vue 3.5+) -->
147<script setup>
148import { useTemplateRef } from 'vue'
149const element = useTemplateRef('my-element') // Any variable name
150</script>
151<template>
152  <div ref="my-element"></div>
153</template>
154```
155 
156## Reference
157- [Vue.js Template Refs - Composition API](https://vuejs.org/guide/essentials/template-refs.html#accessing-the-refs)
158- [Vue 3.5 Release Notes](https://blog.vuejs.org/posts/vue-3-5)
159