1---
2title: Template Refs Become Null When Elements Are Unmounted
3impact: MEDIUM
4impactDescription: Refs become null when conditionally rendered elements are removed, causing errors if not handled
5type: gotcha
6tags: [vue3, template-refs, v-if, watchers, conditional-rendering]
7---
8 
9# Template Refs Become Null When Elements Are Unmounted
10 
11**Impact: MEDIUM** - When using template refs with `v-if`, the ref becomes `null` when the element is unmounted. Watchers and effects that access these refs must handle the null case to avoid runtime errors.
12 
13This is especially tricky with `watchEffect` since it runs automatically and may execute when the ref is null.
14 
15## Task Checklist
16 
17- [ ] Always check for null before accessing ref properties when using v-if
18- [ ] In watchers, explicitly handle the null case (element unmounted or not yet mounted)
19- [ ] Consider whether v-show is more appropriate if you need persistent ref access
20- [ ] Use optional chaining (?.) when accessing ref properties in uncertain contexts
21 
22**Incorrect:**
23```vue
24<script setup>
25import { ref, watchEffect } from 'vue'
26 
27const inputEl = ref(null)
28const showInput = ref(true)
29 
30// WRONG: No null check - will error when v-if is false
31watchEffect(() => {
32  inputEl.value.focus() // TypeError when showInput is false
33})
34</script>
35 
36<template>
37  <input v-if="showInput" ref="inputEl" />
38  <button @click="showInput = !showInput">Toggle</button>
39</template>
40```
41 
42**Correct:**
43```vue
44<script setup>
45import { ref, watchEffect } from 'vue'
46 
47const inputEl = ref(null)
48const showInput = ref(true)
49 
50// CORRECT: Handle both mounted and unmounted states
51watchEffect(() => {
52  if (inputEl.value) {
53    inputEl.value.focus()
54  } else {
55    // Element not mounted yet, or unmounted by v-if
56    console.log('Input element not available')
57  }
58})
59</script>
60 
61<template>
62  <input v-if="showInput" ref="inputEl" />
63  <button @click="showInput = !showInput">Toggle</button>
64</template>
65```
66 
67```vue
68<script setup>
69import { ref, watch } from 'vue'
70 
71const inputEl = ref(null)
72const showInput = ref(true)
73 
74// CORRECT: Watch the ref and handle null explicitly
75watch(inputEl, (el) => {
76  if (el) {
77    el.focus()
78  }
79})
80</script>
81 
82<template>
83  <input v-if="showInput" ref="inputEl" />
84</template>
85```
86 
87```vue
88<script setup>
89import { useTemplateRef, watchEffect } from 'vue'
90 
91// Vue 3.5+ approach
92const input = useTemplateRef('my-input')
93 
94// CORRECT: Use optional chaining for safe access
95watchEffect(() => {
96  input.value?.focus()
97})
98</script>
99 
100<template>
101  <input v-if="showInput" ref="my-input" />
102</template>
103```
104 
105```vue
106<script setup>
107import { ref, onMounted } from 'vue'
108 
109const inputEl = ref(null)
110const showInput = ref(true)
111 
112// ALTERNATIVE: Use v-show if you need consistent ref access
113// v-show keeps element in DOM, just hides it with CSS
114</script>
115 
116<template>
117  <!-- Element always exists in DOM, ref is never null -->
118  <input v-show="showInput" ref="inputEl" />
119</template>
120```
121 
122## Reference
123- [Vue.js Template Refs](https://vuejs.org/guide/essentials/template-refs.html)
124