1---
2title: Suspense Component Best Practices
3impact: MEDIUM
4impactDescription: Suspense coordinates async dependencies with fallback UI; misconfiguration leads to missing loading states or confusing UX
5type: best-practice
6tags: [vue3, suspense, async-components, async-setup, loading, fallback, router, transition, keepalive]
7---
8 
9# Suspense Component Best Practices
10 
11**Impact: MEDIUM** - `<Suspense>` coordinates async dependencies (async components or async setup) and renders a fallback while they resolve. Misconfiguration leads to missing loading states, empty renders, or subtle UX bugs.
12 
13## Task List
14 
15- Wrap default and fallback slot content in a single root node
16- Use `timeout` when you need the fallback to appear on reverts
17- Force root replacement with `:key` when you need Suspense to re-trigger
18- Add `suspensible` to nested Suspense boundaries (Vue 3.3+)
19- Use `@pending`, `@resolve`, and `@fallback` for programmatic loading state
20- Nest `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` in that order
21- Keep Suspense usage centralized and documented in production
22 
23## Single Root in Default and Fallback Slots
24 
25Suspense tracks a single immediate child in both slots. Wrap multiple elements in a single element or component.
26 
27**BAD:**
28```vue
29<template>
30  <Suspense>
31    <AsyncHeader />
32    <AsyncList />
33 
34    <template #fallback>
35      <LoadingSpinner />
36      <LoadingHint />
37    </template>
38  </Suspense>
39</template>
40```
41 
42**GOOD:**
43```vue
44<template>
45  <Suspense>
46    <div>
47      <AsyncHeader />
48      <AsyncList />
49    </div>
50 
51    <template #fallback>
52      <div>
53        <LoadingSpinner />
54        <LoadingHint />
55      </div>
56    </template>
57  </Suspense>
58</template>
59```
60 
61## Fallback Timing on Reverts (`timeout`)
62 
63When Suspense is already resolved and new async work starts, the previous content remains visible until the timeout elapses. Use `timeout="0"` for immediate fallback or a short delay to avoid flicker.
64 
65**BAD:**
66```vue
67<template>
68  <Suspense>
69    <component :is="currentView" :key="viewKey" />
70 
71    <template #fallback>
72      Loading...
73    </template>
74  </Suspense>
75</template>
76```
77 
78**GOOD:**
79```vue
80<template>
81  <Suspense :timeout="200">
82    <component :is="currentView" :key="viewKey" />
83 
84    <template #fallback>
85      Loading...
86    </template>
87  </Suspense>
88</template>
89```
90 
91## Pending State Only Re-triggers on Root Replacement
92 
93Once resolved, Suspense only re-enters pending when the root node of the default slot changes. If async work happens deeper in the tree, no fallback appears.
94 
95**BAD:**
96```vue
97<template>
98  <Suspense>
99    <TabContainer>
100      <AsyncDashboard v-if="tab === 'dashboard'" />
101      <AsyncSettings v-else />
102    </TabContainer>
103 
104    <template #fallback>
105      Loading...
106    </template>
107  </Suspense>
108</template>
109```
110 
111**GOOD:**
112```vue
113<template>
114  <Suspense>
115    <component :is="tabs[tab]" :key="tab" />
116 
117    <template #fallback>
118      Loading...
119    </template>
120  </Suspense>
121</template>
122```
123 
124## Use `suspensible` for Nested Suspense (Vue 3.3+)
125 
126Nested Suspense boundaries need `suspensible` on the inner boundary so the parent can coordinate loading state. Without it, inner async content may render empty nodes until resolved.
127 
128**BAD:**
129```vue
130<template>
131  <Suspense>
132    <LayoutShell>
133      <Suspense>
134        <AsyncWidget />
135        <template #fallback>Loading widget...</template>
136      </Suspense>
137    </LayoutShell>
138 
139    <template #fallback>Loading layout...</template>
140  </Suspense>
141</template>
142```
143 
144**GOOD:**
145```vue
146<template>
147  <Suspense>
148    <LayoutShell>
149      <Suspense suspensible>
150        <AsyncWidget />
151        <template #fallback>Loading widget...</template>
152      </Suspense>
153    </LayoutShell>
154 
155    <template #fallback>Loading layout...</template>
156  </Suspense>
157</template>
158```
159 
160## Track Loading with Suspense Events
161 
162Use `@pending`, `@resolve`, and `@fallback` for analytics, global loading indicators, or coordinating UI outside the Suspense boundary.
163 
164```vue
165<script setup>
166import { ref } from 'vue'
167 
168const isLoading = ref(false)
169 
170const onPending = () => {
171  isLoading.value = true
172}
173 
174const onResolve = () => {
175  isLoading.value = false
176}
177</script>
178 
179<template>
180  <LoadingBar v-if="isLoading" />
181 
182  <Suspense @pending="onPending" @resolve="onResolve">
183    <AsyncPage />
184    <template #fallback>
185      <PageSkeleton />
186    </template>
187  </Suspense>
188</template>
189```
190 
191## Recommended Nesting with RouterView, Transition, KeepAlive
192 
193When combining these components, the nesting order should be `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` so each wrapper works correctly.
194 
195**BAD:**
196```vue
197<template>
198  <RouterView v-slot="{ Component }">
199    <Suspense>
200      <KeepAlive>
201        <Transition mode="out-in">
202          <component :is="Component" />
203        </Transition>
204      </KeepAlive>
205    </Suspense>
206  </RouterView>
207</template>
208```
209 
210**GOOD:**
211```vue
212<template>
213  <RouterView v-slot="{ Component }">
214    <Transition mode="out-in">
215      <KeepAlive>
216        <Suspense>
217          <component :is="Component" />
218          <template #fallback>Loading...</template>
219        </Suspense>
220      </KeepAlive>
221    </Transition>
222  </RouterView>
223</template>
224```
225 
226## Treat Suspense Cautiously in Production
227 
228In production code, keep Suspense boundaries minimal, document where they are used, and have a fallback loading strategy if you ever need to replace or refactor them.
229