1---
2title: Suspense Overrides Async Component Loading and Error Options
3impact: MEDIUM
4impactDescription: Async component loading/error options are ignored under a parent Suspense, leading to missing spinners and error UIs
5type: gotcha
6tags: [vue3, suspense, async-components, loading, error-handling]
7---
8 
9# Suspense Overrides Async Component Loading and Error Options
10 
11**Impact: MEDIUM** - When an async component renders inside a parent `<Suspense>`, its `loadingComponent`, `errorComponent`, `delay`, and `timeout` options do not run. The parent Suspense controls loading and error UX instead.
12 
13## Task Checklist
14 
15- [ ] Confirm whether the async component is inside a `<Suspense>` boundary
16- [ ] Use `suspensible: false` when the component must manage its own loading/error UI
17- [ ] Or move loading/error UI to the parent `<Suspense>` fallback and an error boundary (`onErrorCaptured`)
18- [ ] Provide a retry path for failed loads
19 
20**Incorrect:**
21```vue
22<script setup>
23import { defineAsyncComponent } from 'vue'
24 
25const AsyncDashboard = defineAsyncComponent({
26  loader: () => import('./Dashboard.vue'),
27  loadingComponent: LoadingSpinner,
28  errorComponent: ErrorDisplay,
29  timeout: 3000
30})
31</script>
32 
33<template>
34  <Suspense>
35    <AsyncDashboard />
36    <template #fallback>Loading...</template>
37  </Suspense>
38</template>
39```
40 
41**Correct (component handles its own states):**
42```vue
43<script setup>
44import { defineAsyncComponent } from 'vue'
45 
46const AsyncDashboard = defineAsyncComponent({
47  loader: () => import('./Dashboard.vue'),
48  loadingComponent: LoadingSpinner,
49  errorComponent: ErrorDisplay,
50  timeout: 3000,
51  suspensible: false
52})
53</script>
54 
55<template>
56  <AsyncDashboard />
57</template>
58```
59 
60**Correct (parent Suspense owns loading/error UI):**
61```vue
62<script setup>
63import { onErrorCaptured, ref } from 'vue'
64import AsyncDashboard from './AsyncDashboard.vue'
65 
66const error = ref(null)
67 
68onErrorCaptured((err) => {
69  error.value = err
70  return false
71})
72</script>
73 
74<template>
75  <ErrorDisplay v-if="error" :error="error" />
76 
77  <Suspense v-else>
78    <AsyncDashboard />
79    <template #fallback>
80      <LoadingSpinner />
81    </template>
82  </Suspense>
83</template>
84```
85