Spencer Carney

The Quirks of React's Suspense and Transitions

I spent 2024 working on refactoring a CRA SPA to a Next.js app using Relay to fetch data. Over the course of this project I have found myself using React’s Suspense and Transitions a lot more than I did previously. I had very minimal experience with Suspense but none when it came to Transitions.

After months of using <Suspense>, useTransition, useLazyLoadQuery, useQueryLoader, and loading.tsx, I realized I still couldn’t confidently explain their quirks. This post is my deep dive into how Transitions work, along with some unexpected behaviors I encountered.

React Transitions

What exactly is a Transition? As explained in the React v18.0 blog posted on March 29, 2022, Transitions are used to “distinguish between urgent and non-urgent updates”.

For example, when you select a filter in a dropdown, you expect the filter button itself to respond immediately when you click. However, the actual results may transition separately. A small delay would be imperceptible and often expected. And if you change the filter again before the results are done rendering, you only care to see the latest results.

Typically, for the best user experience, a single user input should result in both an urgent update and a non-urgent one.

An interesting explanation nonetheless, it does not adequately capture how Transitions work, and how to use them. A contrived example is in order.

Select Your Favorite Dessert

Here’s an autocomplete for selecting a dessert that does not use <Suspense>.

When you select a dessert that has flavor options (there are no flavor options for “Mom’s Famous Chocolate Chip Cookies”), another autocomplete is rendered below it, prompting you to select a dessert flavor. The flavors are fetched from an API, which means we want to show a loading state while that fetch is happening. Once the flavors have finished loading, <FlavorAutocomplete>’s loading state has been replaced with flavors for the dessert option you chose. (If the dessert has flavor options.)

Suspense is not being used to render a fallback UI while the data is loading. Even if there was Suspense being used, the data fetching itself is not “Suspense-enabled”.

Suspense-enabled

Per React’s documentation, “Suspense-enabled” means the following:

  1. Data fetching with Suspense-enabled frameworks like Relay and Next.js
  2. Lazy-loading component code with lazy
  3. Reading the value of a cached Promise with use

In the example below, the <FlavorAutocomplete> component triggers a Transition when it fetches data. However the <FlavorAutocomplete> does not have its own Suspense wrapped around it. This causes the Transition to show the nearest parent’s Suspense fallback. That happens to be app’s Suspense. Selecting a dessert will show the “App Loading…” UI from the app’s Suspense fallback.

<Suspense fallback="App Loading...">
  <DessertAutocomplete onChange={handleChange} />

  {selectedDessert && selectedDessert.value !== "famous_cookies" && (
    <FlavorAutocomplete {...} />
  )}
</Suspense>

You can think of <Suspense> as a boundary that catches Transitions bubbling up from its child components. When a Transition occurs, Suspense temporarily replaces the affected UI with a fallback, making loading states easier to manage. This reduces code that we would otherwise write and manage ourselves.

What we want is to show loading UI for the <FlavorAutocomplete> only.

Wrapping our <FlavorAutocomplete> with its own Suspense prevents the Transition from “bubbling up ” unnecessarily to the wrong Suspense. Selecting a dessert in the next example, the user will see a message like “Loading <selected dessert> flavors…” coming from the Suspense that is wrapping the <FlavorAutocomplete>.

<Suspense fallback="App Loading...">
  <DessertAutocomplete onChange={handleChange} />

  <Suspense fallback={`Loading ${selectedDessert?.label} flavors...`}>
    {selectedDessert && selectedDessert.value !== "famous_cookies" && (
      <FlavorAutocomplete {...} />
    )}
  </Suspense>
</Suspense>

Success! We have set up our <FlavorAutocomplete> with Suspense to show the correct loading UI. Feel free to read React’s own documentation on the Suspense to learn more about how this works.

Tapping Into The Suspended Component’s Loading State

Our <FlavorAutocomplete> comes with its own loading state. Below is an example of what that loading state looks like, three pulsating dots. Clicking the <FlavorAutocomplete> while it is loading will show a “Loading…” text where the options would be.

If our <FlavorAutocomplete> is wrapped in a Suspense, it will replace <FlavorAutocomplete> with the fallback UI while fetching data. The drawback to this is that we can not use <FlavorAutocomplete>’s own loading UI.

Why would we want to use <FlavorAutocomplete>’s own loading UI over the Suspense fallback?

Our form could have a number of inputs that do not rely on asynchronous data. Showing all of the inputs immediately would be preferred over loading UI that blocks the user from interacting with the non-async inputs. But Suspense is all-or-nothing. However, without a Suspense component, the Transition from fetching desserts flavors could “bubble up” to the wrong Suspense, resulting in an undesirable experience.

How can we use Suspense while showing our <FlavorAutocomplete> in a loading state?

Dummy Fallback Select

One way to achieve an interactive form that uses Suspense would be to create a “dummy” <FallbackFlavorAutocomplete> component that we render with the fallback prop. You end up with a fully functioning <FlavorAutocomplete> input that is displaying a “loading” state. Once your actual <FlavorAutocomplete> has finished fetching data, you show that instead.

<Suspense fallback={<FallbackFlavorAutocomplete />}>
  <FlavorAutocomplete />
</Suspense>

A problem with this dummy fallback approach is apparent when the user tries to interact with <FallbackFlavorAutocomplete> while the <FlavorAutocomplete> is suspended.

A user clicking on <FallbackFlavorAutocomplete> will see an empty dropdown list with the word “Loading…“. If the select is open when the data has finished fetching, the dropdown will close on them. That is because <FallbackFlavorAutocomplete> is being replaced with <FlavorAutocomplete>. This can be a jarring experience for the user.

We could make it so that the user is unable to open the dropdown on the dummy fallback select. Why would we not want to do this? There’s a reason why select components that asynchronously load their options will show an empty dropdown that says “Loading…”: its enhances the user experience, if only a little.

Albeit contrived, real world examples of this problem do exist. But there is a solution: startTransition.

startTransition

Suspense helps handle loading states bubbling up, but what if we need to manage loading within a component? That’s where startTransition comes in. The useTransition hook (and the isPending value it gives us) should be able to help with this.

const [dessert, setDessert] = useState(null);
const [isPending, startTransition] = useTransition();

const handleClick = (dessert) => {
  startTransition(() => {
    setDessert(dessert);
  });
};

By calling setDessert in startTransition, we should be able to render <FlavorAutocomplete> in a loading state due the isLoading={isPending} prop we pass to it.

This is the code we are using to render <FlavorAutocomplete>.

{dessert && <FlavorAutocomplete loading={isPending} />}

Let’s give it a shot.

That’s interesting. Did you catch that?

The first time a dessert with flavors is selected, there is no change to the UI until the Transition has finished. Subsequent Transitions will result in the <FlavorAutocomplete> being rendered in a loading state for the duration of the Transition. The “Select a <dessert> flavor” text does not update until the Transition has completed.

Why do we not see the <FlavorAutocomplete> immediately when the first Transition has started? Since <FlavorAutocomplete> was not initially rendered, it did not show up until after that first Transition completed.

While isPending can help with showing a loading state, it can only do so after the component has been mounted.

Conditionally Loading With isPending

While we can not use isPending in the first render of a component that was mounted in response to a Transition, we can use that Transition’s isPending in other ways. The example below follows the same logic as the one above, with one exception: the text of isPending: true is being rendered as soon as the first Transition starts, with the following code:

{isPending && "isPending: true"}
{dessert && <FlavorAutocomplete isLoading={isPending} />}

See it in action:

But this one appears to have an easy fix, right?

{isPending && "isPending: true"}
{(isPending || dessert) && <FlavorAutocomplete isLoading={isPending} />}

Nope.

This doesn’t just delay <FlavorAutocomplete> on the first Transition—it never renders during any Transition, breaking our expected behavior.

Console Logging isPending Breaks My Brain

isPending behaves oddly in logs: the render-time value flips to false almost immediately, while useEffect correctly reflects the duration of the Transition.

const [isPending, startTransition] = useTransition();

console.log("on render", { isPending });

useEffect(() => {
  console.log("in useEffect", { isPending });
}, [isPending]);

The “on render” console log will show the value as true, immediately followed by it changing back to false. This is different from the “in useEffect” console log which shows true for the duration of the Transition, switching back to false when the Transition has completed.

Open your browser dev tools and see for yourself:

As a champion console logger, this was an interesting quirk to discover.

Conclusion

While working on a large-scale effort to convert a CRA app to Next.js, I was working more with Suspense and Transitions—concepts that I had only lightly explored before. While Suspense provided a powerful mechanism for handling async rendering, its behavior wasn’t always intuitive, particularly in how Transitions interacted with it. While, useTransition allows for finer control over Transitions, its quirks—like not affecting the initial render—make it an imperfect solution for some use cases.