1# Async Components with keep-alive Ref Issues
2 
3## Rule
4 
5When using `<keep-alive>`, `<component>`, and `defineAsyncComponent` together, be aware that template refs can become undefined when the component is re-activated after being deactivated.
6 
7## Why This Matters
8 
9This is a known Vue issue where the ref binding works correctly on first activation but becomes undefined on subsequent activations. This can cause runtime errors when trying to access component methods or properties through refs.
10 
11## Problem Scenario
12 
13```vue
14<script setup>
15import { ref, defineAsyncComponent } from 'vue'
16 
17const AsyncWidget = defineAsyncComponent(() =>
18  import('./Widget.vue')
19)
20 
21const currentComponent = ref(AsyncWidget)
22const widgetRef = ref(null)
23 
24function callWidgetMethod() {
25  // May be undefined after component reactivation!
26  widgetRef.value?.doSomething()
27}
28</script>
29 
30<template>
31  <keep-alive>
32    <component :is="currentComponent" ref="widgetRef" />
33  </keep-alive>
34</template>
35```
36 
37## Workarounds
38 
39### Option 1: Use onActivated to re-establish ref access
40 
41```vue
42<script setup>
43import { ref, defineAsyncComponent, onActivated, nextTick } from 'vue'
44 
45const AsyncWidget = defineAsyncComponent(() =>
46  import('./Widget.vue')
47)
48 
49const currentComponent = ref(AsyncWidget)
50const widgetRef = ref(null)
51 
52// Use a computed or method that waits for ref to be available
53async function callWidgetMethod() {
54  await nextTick()
55  if (widgetRef.value) {
56    widgetRef.value.doSomething()
57  }
58}
59</script>
60```
61 
62### Option 2: Avoid mixing all three patterns
63 
64If possible, use one of these alternatives:
65 
66```vue
67<!-- Option A: Don't use keep-alive with async components -->
68<template>
69  <component :is="currentComponent" ref="widgetRef" />
70</template>
71 
72<!-- Option B: Use static component with keep-alive -->
73<script setup>
74import Widget from './Widget.vue'  // Regular import
75</script>
76<template>
77  <keep-alive>
78    <component :is="Widget" ref="widgetRef" />
79  </keep-alive>
80</template>
81```
82 
83### Option 3: Use provide/inject instead of refs
84 
85```vue
86<!-- Parent.vue -->
87<script setup>
88import { provide, ref } from 'vue'
89 
90const sharedState = ref({ /* shared data */ })
91provide('widgetState', sharedState)
92</script>
93 
94<!-- Widget.vue (async component) -->
95<script setup>
96import { inject } from 'vue'
97const widgetState = inject('widgetState')
98</script>
99```
100 
101## Key Points
102 
1031. This is a known issue when combining `<keep-alive>`, `<component :is>`, and `defineAsyncComponent`
1042. Refs may become undefined after component deactivation/reactivation
1053. Use `nextTick` and null checks when accessing refs
1064. Consider alternative patterns like provide/inject for cross-component communication
1075. Test thoroughly when using this combination
108 
109## References
110 
111- [Vue.js GitHub Discussion #11334](https://github.com/orgs/vuejs/discussions/11334)
112- [Vue.js Async Components Documentation](https://vuejs.org/guide/components/async)
113