Up to date
Published
4 min read

Trevor I. Lasn

Staff Software Engineer, Engineering Manager

Understanding Vue's Suspense

How the Suspense component manages async dependencies and improves loading states in Vue apps

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.

<Suspense>
<!-- Component with async dependencies -->
<UserProfile />
<!-- Loading state via #fallback slot -->
<template #fallback>
<div class="spinner">Loading user profile...</div>
</template>
</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>.
const data = await fetchData();
<template>
<div>{{ data }}</div>
</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>.
export default {
async setup() {
const data = await fetchData();
return { data };
}
}
<template>
<div>{{ data }}</div>
</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.
<Suspense @pending="handlePending">
<template #default>
<UserProfile />
</template>
<template #fallback>
<div class="spinner">Loading...</div>
</template>
</Suspense>
function handlePending() {
console.log('Loading state started');
}
  • resolve: Emitted once the content in the #default slot has finished loading and is ready to be displayed.
<Suspense @resolve="handleResolve">
<template #default>
<UserProfile />
</template>
<template #fallback>
<div class="spinner">Loading...</div>
</template>
</Suspense>
function handleResolve() {
console.log('Content fully loaded');
}
  • fallback: Fired when the #fallback slot content is shown, typically while waiting for async operations to complete.
<Suspense @fallback="handleFallback">
<template #default>
<UserProfile />
</template>
<template #fallback>
<div class="spinner">Loading...</div>
</template>
</Suspense>
function handleFallback() {
console.log('Showing fallback content');
}

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.

<Suspense>
<!-- Dashboard with async data -->
<UserDashboard />
<!-- Custom loading state -->
<template #fallback>
<div class="loading">Loading dashboard, please wait...</div>
</template>
</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.

<RouterView v-slot="{ Component }">
<template v-if="Component">
<Transition mode="out-in">
<KeepAlive>
<Suspense>
<!-- Main settings content -->
<component :is="Component" />
<!-- Loading spinner -->
<template #fallback>
<div class="loading">Loading settings...</div>
</template>
</Suspense>
</KeepAlive>
</Transition>
</template>
</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.

<Suspense>
<AsyncUserProfile>
<Suspense suspensible>
<AsyncUserDetails />
</Suspense>
</AsyncUserProfile>
</Suspense>

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


Found this article helpful? You might enjoy my free newsletter. I share dev tips and insights to help you grow your coding skills and advance your tech career.

Interested in supporting this blog in exchange for a shoutout? Get in touch.


Liked this post?

Check out these related articles that might be useful for you. They cover similar topics and provide additional insights.

Webdev
4 min read

LH and RLH: The CSS Units That Make Vertical Spacing Easy

Exploring new CSS line-height units that eliminate guesswork from vertical rhythm

Dec 3, 2024
Read article
Webdev
4 min read

Mental Toughness is the Best Quality a Developer Can Have

Mental toughness gets developers through challenges like debugging, picking up new tools, and hitting tight deadlines. It’s about staying calm and pushing through when things get tough.

Sep 12, 2024
Read article
Webdev
3 min read

CSS content-visibility: The Web Performance Boost You Might Be Missing

The content-visibility CSS property delays rendering an element, including layout and painting, until it is needed

Dec 5, 2024
Read article
Webdev
3 min read

CSS ::target-text for Text Highlighting

A look at how browsers can highlight text fragments using CSS ::target-text, making text sharing and navigation more user-friendly

Dec 17, 2024
Read article
Webdev
6 min read

Inside the CSS Engine: CSSOM Explained

A deep dive into how browsers parse and manipulate CSS, its impact on web performance, and why it matters

Oct 25, 2024
Read article
Webdev
3 min read

CSS @supports: Write Future-Proof CSS

Detect CSS feature support and provide smart fallbacks with @supports

Dec 6, 2024
Read article
Webdev
12 min read

Frontend Security Checklist

Tips for Keeping All Frontend Applications Secure

Jul 30, 2024
Read article
Webdev
5 min read

SecretLint — A Linter for Preventing Committing Credentials

A guide to catching and preventing credential leaks in your code using Secretlint

Oct 22, 2024
Read article
Webdev
13 min read

10 Essential Terminal Commands Every Developer Should Know

List of useful Unix terminal commands to boost your productivity. Here are some of my favorites.

Aug 21, 2024
Read article

This article was originally published on https://www.trevorlasn.com/blog/understanding-vue-suspense. It was written by a human and polished using grammar tools for clarity.