React Suspense: Manage Loading States Declaratively

Why it exists

Before Suspense, developers manually managed loading states with useState and conditional rendering (isLoading ? <Spinner /> : <Data />). This cluttered components with boilerplate logic and tightly coupled parent components to their children's data-fetching status. Suspense was created to handle this declaratively, moving the responsibility of orchestrating loading fallbacks to React itself.

The mental model

Think of Suspense as an error boundary, but for loading states. When a component deep in the tree "suspends" — pauses rendering to wait for something like data or code — it signals this to React. The nearest <Suspense> boundary above it "catches" this suspension and displays its fallback UI until the child is ready. This lets you manage loading states without prop-drilling isLoading flags.

How it works

You wrap a component that performs an asynchronous operation in a <Suspense> component. You provide a fallback prop, which is a lightweight component like a spinner or a skeleton loader. When the child component suspends, React walks up the tree to find the nearest <Suspense> boundary. It then renders the fallback UI in its place. Once the async operation completes and the child component can render, React seamlessly replaces the fallback with the actual component UI.

When to use it

Use Suspense to handle loading states for components that fetch data, especially with modern frameworks like Next.js or Relay that have built-in support. It's also the standard way to handle code splitting with React.lazy(), where you want to show a fallback while a component's JavaScript bundle is being downloaded. It simplifies component architecture by isolating async logic.

When not to use it

Suspense is not for handling all async operations. For state updates tied to user input, like a form submission, you should use transitions (useTransition) instead. Also, if your data-fetching library doesn't support Suspense (i.e., it doesn't integrate with React's rendering mechanism), you will have to fall back to manual isLoading state management.

One canonical example

A common use case is showing a skeleton UI while fetching a list of items. The Albums component fetches its own data. By wrapping it in Suspense, the parent component doesn't need to know about the loading state of Albums. <Suspense fallback={<AlbumSkeleton />}> <Albums /> </Suspense> Here, if Albums suspends to fetch data, React will render <AlbumSkeleton />. Once the data is ready, React automatically replaces the skeleton with the fully rendered Albums component.