1---
2title: Template Refs Are Null Until Mounted
3impact: HIGH
4impactDescription: Accessing template ref before mount or after unmount causes runtime errors
5type: gotcha
6tags: [vue3, typescript, template-refs, lifecycle, null-safety]
7---
8 
9# Template Refs Are Null Until Mounted
10 
11**Impact: HIGH** - Template refs have an initial value of `null` and remain null until the component mounts. They can also become null again if the referenced element is removed by `v-if`. Always account for this in TypeScript with union types and optional chaining.
12 
13## Task Checklist
14 
15- [ ] Always type template refs with `| null` union
16- [ ] Only access refs inside `onMounted` or after
17- [ ] Use optional chaining (`?.`) when accessing ref properties
18- [ ] Handle `v-if` scenarios where ref can become null again
19- [ ] Consider using `useTemplateRef` in Vue 3.5+
20 
21## The Problem
22 
23```vue
24<script setup lang="ts">
25import { ref } from 'vue'
26 
27// WRONG: Doesn't account for null
28const inputRef = ref<HTMLInputElement>()
29 
30// WRONG: Will crash if accessed before mount
31inputRef.value.focus()  // Error: Cannot read properties of null
32 
33// WRONG: Accessed in setup, element doesn't exist yet
34console.log(inputRef.value.value)  // Error!
35</script>
36 
37<template>
38  <input ref="inputRef" />
39</template>
40```
41 
42## The Solution
43 
44```vue
45<script setup lang="ts">
46import { ref, onMounted } from 'vue'
47 
48// CORRECT: Include null in the type
49const inputRef = ref<HTMLInputElement | null>(null)
50 
51// CORRECT: Access in onMounted when DOM exists
52onMounted(() => {
53  inputRef.value?.focus()  // Safe with optional chaining
54})
55 
56// CORRECT: Guard before accessing
57function focusInput() {
58  if (inputRef.value) {
59    inputRef.value.focus()
60  }
61}
62</script>
63 
64<template>
65  <input ref="inputRef" />
66</template>
67```
68 
69## Vue 3.5+: useTemplateRef
70 
71Vue 3.5 introduces `useTemplateRef` with better type inference:
72 
73```vue
74<script setup lang="ts">
75import { useTemplateRef, onMounted } from 'vue'
76 
77// Type is automatically inferred for static refs
78const inputRef = useTemplateRef<HTMLInputElement>('input')
79 
80onMounted(() => {
81  inputRef.value?.focus()
82})
83</script>
84 
85<template>
86  <input ref="input" />
87</template>
88```
89 
90## Handling v-if Scenarios
91 
92Refs can become `null` when elements are conditionally rendered:
93 
94```vue
95<script setup lang="ts">
96import { ref, watch } from 'vue'
97 
98const showModal = ref(false)
99const modalRef = ref<HTMLDivElement | null>(null)
100 
101// WRONG: Assuming ref always exists after first mount
102function closeModal() {
103  modalRef.value.classList.remove('open')  // May be null!
104}
105 
106// CORRECT: Always guard access
107function closeModal() {
108  modalRef.value?.classList.remove('open')
109}
110 
111// CORRECT: Watch for ref changes
112watch(modalRef, (newRef) => {
113  if (newRef) {
114    // Modal element just mounted
115    newRef.focus()
116  }
117  // If null, modal was unmounted
118})
119</script>
120 
121<template>
122  <div v-if="showModal" ref="modalRef" class="modal">
123    Modal content
124  </div>
125</template>
126```
127 
128## Component Refs
129 
130For component refs, use `InstanceType`:
131 
132```vue
133<script setup lang="ts">
134import { ref, onMounted } from 'vue'
135import ChildComponent from './ChildComponent.vue'
136 
137// Component ref with null
138const childRef = ref<InstanceType<typeof ChildComponent> | null>(null)
139 
140onMounted(() => {
141  // Access exposed methods/properties
142  childRef.value?.exposedMethod()
143})
144</script>
145 
146<template>
147  <ChildComponent ref="childRef" />
148</template>
149```
150 
151Remember: Child components must use `defineExpose` to expose methods:
152 
153```vue
154<!-- ChildComponent.vue -->
155<script setup lang="ts">
156function exposedMethod() {
157  console.log('Called from parent')
158}
159 
160defineExpose({
161  exposedMethod
162})
163</script>
164```
165 
166## Multiple Refs with v-for
167 
168```vue
169<script setup lang="ts">
170import { ref, onMounted } from 'vue'
171 
172const items = ref(['a', 'b', 'c'])
173 
174// Array of refs for v-for
175const itemRefs = ref<(HTMLLIElement | null)[]>([])
176 
177onMounted(() => {
178  // Access specific item
179  itemRefs.value[0]?.focus()
180 
181  // Iterate safely
182  itemRefs.value.forEach(el => {
183    el?.classList.add('mounted')
184  })
185})
186</script>
187 
188<template>
189  <ul>
190    <li
191      v-for="(item, index) in items"
192      :key="item"
193      :ref="el => { itemRefs[index] = el as HTMLLIElement }"
194    >
195      {{ item }}
196    </li>
197  </ul>
198</template>
199```
200 
201## Async Operations and Refs
202 
203Be careful with async operations:
204 
205```vue
206<script setup lang="ts">
207import { ref, onMounted } from 'vue'
208 
209const containerRef = ref<HTMLDivElement | null>(null)
210 
211onMounted(async () => {
212  // containerRef.value exists here
213 
214  await fetchData()
215 
216  // CAREFUL: Component might have unmounted during await
217  // Always re-check before accessing
218  if (containerRef.value) {
219    containerRef.value.scrollTop = 0
220  }
221})
222</script>
223```
224 
225## Type Guard Pattern
226 
227Create a reusable type guard for cleaner code:
228 
229```typescript
230// utils/refs.ts
231export function assertRef<T>(
232  ref: Ref<T | null>,
233  message = 'Ref is not available'
234): asserts ref is Ref<T> {
235  if (ref.value === null) {
236    throw new Error(message)
237  }
238}
239 
240// Usage in component
241function mustFocus() {
242  assertRef(inputRef, 'Input element not mounted')
243  inputRef.value.focus()  // TypeScript knows it's not null here
244}
245```
246 
247## Reference
248- [Vue.js TypeScript with Composition API - Template Refs](https://vuejs.org/guide/typescript/composition-api.html#typing-template-refs)
249- [Vue.js Template Refs](https://vuejs.org/guide/essentials/template-refs.html)
250