The <Suspense> component is an experimental feature in Vue. It’s designed to help manage async dependencies in your component tree.

While it’s still experimental and might change, it offers a powerful way to handle loading states when dealing with async components.

What Problem Does Suspense Solve?

When working with components that depend on async data, you often need to manage loading states manually.

Imagine you have a dashboard component with several nested components, each relying on data fetched asynchronously.

Without <Suspense>, each of these components would need its own loading logic, which could result in multiple spinners or loading indicators popping up at different times. This can create a jarring user experience.

With <Suspense>, you can manage the loading state at a higher level. Instead of each component handling its own loading state, <Suspense> allows you to display a single loading state while waiting for all async dependencies in the component tree to resolve.

How Does <Suspense> Work?

The <Suspense> component works by wrapping other components. It has two slots: #default and #fallback.

1
<Suspense>
2
  <!-- Component with async dependencies -->
3
  <UserProfile />
4

5
  <!-- Loading state via #fallback slot -->
6
  <template #fallback>
7
    <div class="spinner">Loading user profile...</div>
8
  </template>
9
</Suspense>

The #default slot contains the component or content that should be displayed once everything is ready.

The #fallback slot is where you define what should be shown while waiting for the async operations to complete.

When the component renders, Vue tries to render the content in the #default slot. If it encounters any async dependencies (like a component using async setup()), it will switch to the #fallback slot until everything is ready.

Understanding Async Dependencies

There are two types of async dependencies that <Suspense> can wait on:

• Components with async setup() hooks: If a component’s setup function is async, it automatically becomes an async dependency for <Suspense>.

1
const data = await fetchData();
2

3
<template>
4
  <div>{{ data }}</div>
5
</template>

• Async Components: These are components that are explicitly defined as async. If they are part of the <Suspense> component tree, their loading states are managed by <Suspense>.

1
export default {
2
  async setup() {
3
    const data = await fetchData();
4
    return { data };
5
  }
6
}
7

8
<template>
9
  <div>{{ data }}</div>
10
</template>

Handling Events with <Suspense>

The <Suspense> component emits three key events: pending, resolve, and fallback.

• pending: Triggered when the component enters a pending state, indicating that async dependencies are being resolved.

1
<Suspense @pending="handlePending">
2
  <template #default>
3
    <UserProfile />
4
  </template>
5
  <template #fallback>
6
    <div class="spinner">Loading...</div>
7
  </template>
8
</Suspense>
9

10
function handlePending() {
11
  console.log('Loading state started');
12
}

• resolve: Emitted once the content in the #default slot has finished loading and is ready to be displayed.

1
<Suspense @resolve="handleResolve">
2
  <template #default>
3
    <UserProfile />
4
  </template>
5
  <template #fallback>
6
    <div class="spinner">Loading...</div>
7
  </template>
8
</Suspense>
9

10
function handleResolve() {
11
  console.log('Content fully loaded');
12
}

• fallback: Fired when the #fallback slot content is shown, typically while waiting for async operations to complete.

1
<Suspense @fallback="handleFallback">
2
  <template #default>
3
    <UserProfile />
4
  </template>
5
  <template #fallback>
6
    <div class="spinner">Loading...</div>
7
  </template>
8
</Suspense>
9

10
function handleFallback() {
11
  console.log('Showing fallback content');
12
}

Managing the Loading State

The beauty of <Suspense> is in how it manages loading states. When the component is initially rendered, Vue tries to render the default content. If it encounters async operations, it shows the fallback content. Once all async dependencies resolve, the default content is displayed.

1
<Suspense>
2
  <!-- Dashboard with async data -->
3
  <UserDashboard />
4

5
  <!-- Custom loading state -->
6
  <template #fallback>
7
    <div class="loading">Loading dashboard, please wait...</div>
8
  </template>
9
</Suspense>

This makes it easy to manage complex loading scenarios without the need for multiple loading indicators scattered throughout your component tree.

Handling Errors

While <Suspense> is great for managing loading states, it doesn’t directly handle errors. For error handling, you can use Vue’s errorCaptured option or the onErrorCaptured() hook in the parent component.

Combining <Suspense> with Other Vue Components

You might want to use <Suspense> alongside components like <Transition>, <KeepAlive>, or <RouterView>. The nesting order is important here to ensure everything works as expected.

1
<RouterView v-slot="{ Component }">
2
  <template v-if="Component">
3
    <Transition mode="out-in">
4
      <KeepAlive>
5
        <Suspense>
6
          <!-- Main settings content -->
7
          <component :is="Component" />
8

9
          <!-- Loading spinner -->
10
          <template #fallback>
11
            <div class="loading">Loading settings...</div>
12
          </template>
13
        </Suspense>
14
      </KeepAlive>
15
    </Transition>
16
  </template>
17
</RouterView>

The setup above allows you to combine transitions, caching, and async handling smoothly.

Nested <Suspense>

In more complex applications, you might have nested async components. By using nested <Suspense> components, you can control the loading states of deeply nested components independently.

1
<Suspense>
2
  <AsyncUserProfile>
3
    <Suspense suspensible>
4
      <AsyncUserDetails />
5
    </Suspense>
6
  </AsyncUserProfile>
7
</Suspense>

Setting the suspensible prop ensures that the inner <Suspense> integrates with the parent, allowing for more precise control over loading states.s