Aman Explains

Settings

React Suspense for data fetching

March 09, 2025• ☕️☕️ 8 min read

React introduced Suspense API to support code splitting of JS modules in combination with React.lazy(), allowing components to be loaded lazily as needed. 

const HeavyComponentLazy = lazy(() => import('./HeavyComponent'));

// and then wrapping it with Suspense boundary.
<Suspense fallback={<div>Loading...</div>}>
 {isOpen && <HeavyComponentLazy />}
</Suspense>

Loading JavaScript requires parsing, compilation and execution, which is expensive compared to loading an image of the same size. To know about why it’s important to load JS modules lazily and how to implement it, read my another article on how to use React Suspense for lazy loading of JS.

This article explores another use case of the Suspense API for data fetching that not only improves the developer experience by making the loading a declarative concept, but also improves the performance of your app via React concurrent mode.

Note that we won’t be covering the Suspense API integration with React Server components and hydration in this article.

Table of Contents

Why use Suspense for data fetching

As a developer I don’t want to think about loading states in my component; instead I want to focus on the data that my component will render and what my users will be interested in. Suspense for data fetching makes the loading a first-class declarative concept in React programming model allowing you to reduce the conditional rendering logic check everywhere.

Suspense delay rendering until the data is ready. Instead of managing loading at the component level, we manage loading at the Suspense boundary level. It’s no more a responsibility of the component. You can declaratively wrap your component within the Suspense boundary wherever in the tree hierarchy you like.

<Suspense fallback={<div>Loading...</div>}>
  <DataComponent />
</Suspense>

Note that if you have multiple components within a single Suspense boundary, the whole tree, by default, is treated as single unit and will be replaced by a single fallback UI. For example, if you have the following tree: 

<Suspense fallback={<div>Loading...</div>}>
  <DataComponent />
  <StaticComponent />
  <OtherComponent />
</Suspense>

When DataComponent suspends, the whole tree will be replaced by a single fallback UI. This allows you to reveal content together at once. If you want the fallback UI to appear only for specific components, move the Suspense boundary closer to those components.This way, the fallback UI will be shown only in the desired location, rather than replacing the entire tree. 

<Suspense fallback={<div>Loading...</div>}>
  <DataComponent /> {/* Fallback UI will be shown only for this component */}
</Suspense>
  <StaticComponent />
<OtherComponent />

Addiiontally, Suspense supports parallel data fetching for sibling components of suspended component. It means if you have another sibling component with its own data requirement, React will show the fallback immediately, but initiate the fetch for the sibling components without extra renders as well 🚀. This approach optimizes rendering while keeping the benefits of parallel data fetching. For more details on this topic read the official React docs on improvements to Suspense and the React 19 - Final Pre-warming approach discussion on github.

Brief overview of how suspense works

Throwing an error is a common practice for error handling in JavaScript. But throw is not about error handling, it’s about the control flow in your logic. You as a developer can throw anything you like. This is how Suspense work under the hood. A component suspends by throwng a promise which then gets captured in the Suspense boundary. And while Suspense is waiting for the promise to resolve, it will render a fallback UI. Once the promise resolves, it will render the children.

Let’s understand this with an example.

// Creating a dummy suspense-enabled data source
// to throw a promise when data is not available.
const fetchData = () => {
  return new Promise((resolve) => {
    setTimeout(() => resolve("Data Loaded!"), 3000);
  });
};

const resource = (() => {
  let status = "pending";
  let result;
  const promise = fetchData().then((res) => {
    console.log("Promise resolved, scheduling re-render");
    status = "success";
    result = res;
  });

  return {
    read() {
      console.log("read() called, status:", status);
      if (status === "pending") throw promise;
      return result;
    },
  };
})();
export default resouce;

And then we can use this suspense-enabled data source in our component as shown below. 

import { Suspense } from 'react';

const DataComponent = () => {
  const data = resource.read();
  // --> Rendering will pause till data is available (pause rendering)
  return <div>{data}</div>;
}

export default function App() {
// Need to wrap the component in a Suspense boundary
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <DataComponent />
    </Suspense>
  );
}

Here’s the codesandbox example for the code above. Please don’t use the example above in your production code, it’s for illustrative purpose only. We’ll see how to use Suspense for data fetching in upcoming section.

How Suspense integrates with React concurrent features

While component is suspended (waiting for the data), React pauses its rendering and can prioritize other tasks. Once data becomes available, React can resume rendering the previously suspended component in an interruptible manner. This means that if the user interacts with other components, React pauses the ongoing render to prioritize updates to those components. To learn in details I highly recommend reading how Suspense integrates deeply with the concurrent features article by Lydia Halli.

How to use it in your current React project

As per offical React docs you need to have a suspense-enabled data source to activate the Suspense component. They include:

  • Data fetching with Suspense-enabled frameworks like useSuspenseQuery, useSWR, NextJS and Relay.
  • Lazy-loading component code with lazy
  • Reading the value of a cached Promise with use

Example with useSuspenseQuery (React query)

I have been advocating internally in our team to use useSuspenseQuery for the reasons I mentioned above. The developer experience is much better. Let’s take a look.

import { useSuspenseQuery } from "react-query";

const DataComponent = () => {
  const { data } = useSuspenseQuery("user", fetchData);
  return <div>{data}</div>;
};

// Using it in our app. You can control the boundary of this loading UI via Suspense.
export default function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <DataComponent />
    </Suspense>
  );
}

No more thinking about loading states anymore. You are free to use data and render your UI as normal.

Even TypeScript will indicate that the data is not null or undefined. Displaying the loading UI is not the responsibility of this component; we’ve delegated that to the Suspense boundary in the outer shell. This approach is very declarative, allowing you to decide how far up in the hierarchy you want the loading UI to extend.

Note that Suspense is not limited to data fetching and lazy loading JS assets, but you can also lazy load images, css or fonts as well.

Summary

  • Suspense API allows you to delay rendering until the data is available. This is know as Suspense for data fetching. All you need is suspense-enabled sources for this to work.
  • It makes the loading a first-class declarative concept and allow to control the loading states declaratively resulting in a much better developer experience.
  • You can use Suspense for data fetching, lazy loading of JS modules and more.

References

Amandeep Singh

Written by Amandeep Singh. Developer @  Avarni  Sydney. Tech enthusiast and a pragmatic programmer.