Suspense

"Suspense" is both a specific React API (<Suspense />, a component which "lets you display a fallback until its children have finished loading"), and often used more generally to refer to a new way to build React apps using the concurrent rendering engine introduced in React 18.

In this guide, we'll look at Apollo Client's data fetching hooks introduced in 3.8 which leverage React's powerful Suspense features and walk through some examples of how they can be used.

Fetching with Suspense

useSuspenseQuery initiates a network request and causes the component calling it to suspend while the request is made. It can be thought of as a Suspense-ready replacement for useQuery that allows you to take advantage of React's Suspense features while fetching during render.

Let's take a look at an example:

1
import { Suspense } from 'react';
2
import {
3
  gql,
4
  TypedDocumentNode,
5
  useSuspenseQuery
6
} from '@apollo/client';
7

8
interface Data {
9
  dog: {
10
    id: string;
11
    name: string;
12
  };
13
}
14

15
interface Variables {
16
  id: string;
17
}
18

19
interface DogProps {
20
  id: string
21
}
22

23
const GET_DOG_QUERY: TypedDocumentNode<Data, Variables> = gql`
24
  query GetDog($id: String) {
25
    dog(id: $id) {
26
      # By default, an object's cache key is a combination of
27
      # its __typename and id fields, so we should always make
28
      # sure the id is in the response so our data can be
29
      # properly cached.
30
      id
31
      name
32
    }
33
  }
34
`;
35

36
function App() {
37
  return (
38
    <Suspense fallback={<div>Loading...</div>}>
39
      <Dog id="3" />
40
    </Suspense>
41
  );
42
}
43

44
function Dog({ id }: DogProps) {
45
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
46
    variables: { id },
47
  });
48

49
  return <>Name: {data.dog.name}</>;
50
}

In this example, our App component renders a Dog component which fetches the record for a single dog via useSuspenseQuery. When React attempts to render Dog for the first time, the cache is unable to fulfill the request for the GetDog query, so useSuspenseQuery initiates a network request. Dog suspends while the network request is pending, triggering the nearest Suspense boundary above the suspended component in App which renders our "Loading..." fallback. Once the network request is complete, Dog renders with the newly cached name for Mozzarella the Corgi.

You may have noticed that useSuspenseQuery does not return a loading boolean: this is because the component calling useSuspenseQuery will always suspend when fetching data. A corollary is that when it does render, data is always defined! Suspense fallbacks that exist outside of suspended components take the place of loading states that components were responsible for rendering themselves in the previous React paradigm.

Changing variables

In the previous example, we fetched the record for a single dog by passing a hard-coded id variable, Mozzarella, to useSuspenseQuery. Now, let's say we want to fetch the record for a different dog using a dynamic value. We'll fetch the list of dogs with just their name and id, and once the user selects an individual dog we fetch more details, including their breed.

Let's update our example:

1
export const GET_DOG_QUERY: TypedDocumentNode<
2
  DogData,
3
  Variables
4
> = gql`
5
  query GetDog($id: String) {
6
    dog(id: $id) {
7
      id
8
      name
9
      breed
10
    }
11
  }
12
`;
13

14
export const GET_DOGS_QUERY: TypedDocumentNode<
15
  DogsData,
16
  Variables
17
> = gql`
18
  query GetDogs {
19
    dogs {
20
      id
21
      name
22
    }
23
  }
24
`;
25

26
function App() {
27
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
28
  const [selectedDog, setSelectedDog] = useState(
29
    data.dogs[0].id
30
  );
31

32
  return (
33
    <>
34
      <select
35
        onChange={(e) => setSelectedDog(e.target.value)}
36
      >
37
        {data.dogs.map(({ id, name }) => (
38
          <option key={id} value={id}>{dog.name}</option>
39
        ))}
40
      </select>
41
      <Suspense fallback={<div>Loading...</div>}>
42
        <Dog id={selectedDog} />
43
      </Suspense>
44
    </>
45
  );
46
}
47

48
function Dog({ id }: DogProps) {
49
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
50
    variables: { id },
51
  });
52

53
  return (
54
    <>
55
      <div>Name: {data.dog.name}</div>
56
      <div>Breed: {data.dog.breed}</div>
57
    </>
58
  );
59
}

Changing the dog via the select will cause the component to suspend each time we select a dog whose record does not yet exist in the cache. Once we've loaded a given dog's record in the cache, however, selecting that dog again from our dropdown will not cause the component to re-suspend, since under our default cache-first fetch policy Apollo Client will not make a network request after a cache hit.

Updating state without suspending

Sometimes we may want to avoid showing a loading UI in response to a pending network request and instead prefer to continue displaying the previous render. To do this, we can use a transition to mark our update as non-urgent. This tells React to keep the existing UI in place until the new data has finished loading.

To mark a state update as a transition, we use the startTransition function from React.

Let's modify our example so that the previously displayed dog remains on the screen while the next one is fetched in a transition:

1
import { useState, Suspense, startTransition } from "react";
2

3
function App() {
4
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
5
  const [selectedDog, setSelectedDog] = useState(
6
    data.dogs[0].id
7
  );
8

9
  return (
10
    <>
11
      <select
12
        onChange={(e) => {
13
          startTransition(() => {
14
            setSelectedDog(e.target.value);
15
          });
16
        }}
17
      >
18
        {data.dogs.map(({ id, name }) => (
19
          <option key={id} value={id}>{name}</option>
20
        ))}
21
      </select>
22
      <Suspense fallback={<div>Loading...</div>}>
23
        <Dog id={selectedDog} />
24
      </Suspense>
25
    </>
26
  );
27
}

By wrapping our setSelectedDog state update in React's startTransition function, we no longer see the Suspense fallback when selecting a new dog! Instead, the previous dog remains on the screen until the next dog's record has finished loading.

Showing pending UI during a transition

In the previous example, there is no visual indication that a fetch is happening when a new dog is selected. To provide nice visual feedback, let's update our example to use React's useTransition hook which gives you an isPending boolean value to determine when a transition is happening.

Let's dim the select dropdown while the transition is happening:

1
import { useState, Suspense, useTransition } from "react";
2

3
function App() {
4
  const [isPending, startTransition] = useTransition();
5
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
6
  const [selectedDog, setSelectedDog] = useState(
7
    data.dogs[0].id
8
  );
9

10
  return (
11
    <>
12
      <select
13
        style={{ opacity: isPending ? 0.5 : 1 }}
14
        onChange={(e) => {
15
          startTransition(() => {
16
            setSelectedDog(e.target.value);
17
          });
18
        }}
19
      >
20
        {data.dogs.map(({ id, name }) => (
21
          <option key={id} value={id}>{name}</option>
22
        ))}
23
      </select>
24
      <Suspense fallback={<div>Loading...</div>}>
25
        <Dog id={selectedDog} />
26
      </Suspense>
27
    </>
28
  );
29
}

Rendering partial data

When the cache contains partial data, you may prefer to render that data immediately without suspending. To do this, use the returnPartialData option.

Let's update our example to use the partial cache data and render immediately:

1
interface PartialData {
2
  dog: {
3
    id: string;
4
    name: string;
5
  };
6
}
7

8
const PARTIAL_GET_DOG_QUERY: TypedDocumentNode<
9
  PartialData,
10
  Variables
11
> = gql`
12
  query GetDog($id: String) {
13
    dog(id: $id) {
14
      id
15
      name
16
    }
17
  }
18
`;
19

20
// Write partial data for Buck to the cache
21
// so it is available when Dog renders
22
client.writeQuery({
23
  query: GET_DOG_QUERY_PARTIAL,
24
  variables: { id: "1" },
25
  data: { dog: { id: "1", name: "Buck" } },
26
});
27

28
function App() {
29
  const client = useApolloClient();
30

31
  return (
32
    <Suspense fallback={<div>Loading...</div>}>
33
      <Dog id="1" />
34
    </Suspense>
35
  );
36
}
37

38
function Dog({ id }: DogProps) {
39
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
40
    variables: { id },
41
    returnPartialData: true,
42
  });
43

44
  return (
45
    <>
46
      <div>Name: {data?.dog?.name}</div>
47
      <div>Breed: {data?.dog?.breed}</div>
48
    </>
49
  );
50
}

In this example, we write partial data to the cache for Buck to show the behavior when a query cannot be fully fulfilled from the cache. We tell useSuspenseQuery that we are ok rendering partial data by setting the returnPartialData option to true. When Dog renders for the first time, it does not suspend and uses the partial data immediately. Apollo Client will fetch the missing query data from the network in the background.

You will see Buck's name displayed immediately after the Name label, followed by the Breed label with no value. Once the missing fields have loaded, useSuspenseQuery will update and Buck's breed will be displayed.

Error handling

By default, both network errors and GraphQL errors are thrown by useSuspenseQuery. These errors will be caught and displayed by the closest error boundary.

Let's create a basic error boundary that renders an error UI when errors are thrown by our query:

1
class ErrorBoundary extends React.Component {
2
  constructor(props) {
3
    super(props);
4
    this.state = { hasError: false };
5
  }
6

7
  static getDerivedStateFromError(error) {
8
    return { hasError: true };
9
  }
10

11
  render() {
12
    if (this.state.hasError) {
13
      return this.props.fallback;
14
    }
15

16
    return this.props.children;
17
  }
18
}

When the GET_DOG_QUERY inside of the Dog component returns a GraphQL error or a network error, useSuspenseQuery throws the error and the nearest error boundary renders its fallback component.

Our example doesn't have an error boundary yet—let's add one!

1
function App() {
2
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
3
  const [selectedDog, setSelectedDog] = useState(
4
    data.dogs[0].id
5
  );
6

7
  return (
8
    <>
9
      <select
10
        onChange={(e) => setSelectedDog(e.target.value)}
11
      >
12
        {data.dogs.map(({ id, name }) => (
13
          <option key={id} value={id}>
14
            {name}
15
          </option>
16
        ))}
17
      </select>
18
      <ErrorBoundary
19
        fallback={<div>Something went wrong</div>}
20
      >
21
        <Suspense fallback={<div>Loading...</div>}>
22
          <Dog id={selectedDog} />
23
        </Suspense>
24
      </ErrorBoundary>
25
    </>
26
  );
27
}

Here, we're using our ErrorBoundary component and placing it outside of our Dog component. Now, when the useSuspenseQuery hook inside the Dog component throws an error, the ErrorBoundary will catch it and display the fallback element we've provided.

Rendering partial data alongside errors

In some cases, you may want to render partial data alongside an error. To do this, set the errorPolicy option to all. useSuspenseQuery will avoid throwing the error and instead set an error property returned by the hook. To ignore errors altogether, set the errorPolicy to ignore. See the errorPolicy documentation for more information.

Avoiding request waterfalls

Since useSuspenseQuery suspends while data is being fetched, a tree of components that all use useSuspenseQuery can cause a "waterfall", where each call to useSuspenseQuery depends on the previous to complete before it can start fetching. This can be avoided by fetching with useBackgroundQuery and reading the data with useReadQuery.

useBackgroundQuery initiates a request for data in a parent component and returns a queryRef which is passed to useReadQuery to read the data in a child component. When the child component renders before the data has finished loading, the child component will suspend.

Let's update our example to utilize useBackgroundQuery:

1
import {
2
  useBackgroundQuery,
3
  useReadQuery,
4
  useSuspenseQuery,
5
} from '@apollo/client';
6

7
function App() {
8
  // We can start the request here, even though `Dog` 
9
  // suspends and the data is read by a grandchild component.
10
  const [queryRef] = useBackgroundQuery(GET_BREEDS_QUERY);
11

12
  return (
13
    <Suspense fallback={<div>Loading...</div>}>
14
      <Dog id="3" queryRef={queryRef} />
15
    </Suspense>
16
  );
17
}
18

19
function Dog({ id, queryRef }: DogProps) {
20
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
21
    variables: { id },
22
  });
23

24
  return (
25
    <>
26
      Name: {data.dog.name}
27
      <Suspense fallback={<div>Loading breeds...</div>}>
28
        <Breeds queryRef={queryRef} />
29
      </Suspense>
30
    </>
31
  );
32
}
33

34
interface BreedsProps {
35
  queryRef: QueryReference<BreedData>;
36
}
37

38
function Breeds({ queryRef }: BreedsProps) {
39
  const { data } = useReadQuery(queryRef);
40

41
  return data.breeds.map(({ characteristics }) =>
42
    characteristics.map((characteristic) => (
43
      <div key={characteristic}>{characteristic}</div>
44
    ))
45
  );
46
}

We begin fetching our GET_BREEDS_QUERY when the App component renders. The network request is made in the background while React renders the rest of our component tree. When the Dog component renders, it fetches our GET_DOG_QUERY and suspends.

When the network request for GET_DOG_QUERY completes, the Dog component unsuspends and continues rendering, reaching the Breeds component. Since our GET_BREEDS_QUERY request was initiated higher up in our component tree using useBackgroundQuery, the network request for GET_BREEDS_QUERY has already completed! When the Breeds component reads the data from the queryRef provided by useBackgroundQuery, it avoids suspending and renders immediately with the fetched data.

A note about performance

The useBackgroundQuery hook used in a parent component is responsible for kicking off fetches, but doesn't deal with reading or rendering data. This is delegated to the useReadQuery hook used in a child component. This separation of concerns provides a nice performance benefit because cache updates are observed by useReadQuery and will re-render only the child component. You may find this as a useful tool to optimize your component structure to avoid unnecessarily re-rendering parent components when cache data changes.

Refetching and pagination

Apollo's Suspense data fetching hooks return functions for refetching query data via the refetch function, and fetching additional pages of data via the fetchMore function.

Let's update our example by adding the ability to refetch breeds. We destructure the refetch function from the second item in the tuple returned from useBackgroundQuery. We'll be sure to show a pending state to let the user know that data is being refetched by utilizing React's useTransition hook:

1
import { Suspense, useTransition } from "react";
2
import {
3
  useSuspenseQuery,
4
  useBackgroundQuery,
5
  useReadQuery,
6
  gql,
7
  TypedDocumentNode,
8
  QueryReference,
9
} from "@apollo/client";
10

11
function App() {
12
  const [isPending, startTransition] = useTransition();
13
  const [queryRef, { refetch }] = useBackgroundQuery(
14
    GET_BREEDS_QUERY
15
  );
16

17
  function handleRefetch() {
18
    startTransition(() => {
19
      refetch();
20
    });
21
  };
22

23
  return (
24
    <Suspense fallback={<div>Loading...</div>}>
25
      <Dog
26
        id="3"
27
        queryRef={queryRef}
28
        isPending={isPending}
29
        onRefetch={handleRefetch}
30
      />
31
    </Suspense>
32
  );
33
}
34

35
function Dog({
36
  id,
37
  queryRef,
38
  isPending,
39
  onRefetch,
40
}: DogProps) {
41
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
42
    variables: { id },
43
  });
44

45
  return (
46
    <>
47
      Name: {data.dog.name}
48
      <Suspense fallback={<div>Loading breeds...</div>}>
49
        <Breeds isPending={isPending} queryRef={queryRef} />
50
      </Suspense>
51
      <button onClick={onRefetch}>Refetch!</button>
52
    </>
53
  );
54
}
55

56
function Breeds({ queryRef, isPending }: BreedsProps) {
57
  const { data } = useReadQuery(queryRef);
58

59
  return data.breeds.map(({ characteristics }) =>
60
    characteristics.map((characteristic) => (
61
      <div
62
        style={{ opacity: isPending ? 0.5 : 1 }}
63
        key={characteristic}
64
      >
65
        {characteristic}
66
      </div>
67
    ))
68
  );
69
}

In this example, every time the user clicks the "Refetch!" button rendered by the Dog component, our onRefetch handler calls the refetch function returned by useBackgroundQuery which initiates a new network request for the GET_BREEDS_QUERY query. We wrap this in a transition by calling the startTransition function provided by the useTransition hook to avoid rendering our Suspense boundary. This maintains the existing UI while we fetch new data. To provide visual feedback that data is being fetched, we use the isPending boolean to lower the opacity on the list of breeds.

Distinguishing between queries with queryKey

In rare cases, you might need to render multiple components that use the same query and variables combination. Due to the mechanics of Suspense, Apollo Client uses the combination of query and variables to uniquely identify the query when using Apollo's Suspense data fetching hooks.

This presents a problem, however, because it means multiple hooks may end up with the same identity. These hooks will suspend together, regardless of which component initiates or re-initiates a network request.

You can prevent this with queryKey option to ensure each hook has a unique identity. When queryKey is provided, Apollo Client will use as part of the hook's identity in combination with its query and variables.

For more information, see the useSuspenseQuery or useBackgroundQuery API docs.

Skipping suspense hooks

While useSuspenseQuery and useBackgroundQuery both have a skip option, that option is only present to ease migration from useQuery with as few code changes as possible. It should not be used in the long term.

Instead, you should use skipToken:

1
import { skipToken, useSuspenseQuery } from '@apollo/client';
2
const { data } = useSuspenseQuery(
3
  query,
4
  id ? { variables: { id } } : skipToken
5
);

1
import { skipToken, useBackgroundQuery } from '@apollo/client';
2
const [queryRef] = useBackgroundQuery(
3
  query,
4
  id ? { variables: { id } } : skipToken
5
);

React Server Components (RSC)

Usage with Next.js 13 App Router

In Next.js v13, Next.js's new App Router brought the React community the first framework with full support for React Server Components (RSC) and Streaming SSR, integrating Suspense as a first-class concept from your application's routing layer all the way down.

In order to integrate with these features, our Apollo Client team released an experimental package, @apollo/experimental-nextjs-app-support, which allows for seamless use of Apollo Client with both RSC and Streaming SSR, one of the first of its kind for data fetching libraries. See its README and our introductory blog post for more details.

Streaming while fetching with useBackgroundQuery during streaming SSR

In a client-rendered application, useBackgroundQuery can be used to avoid request waterfalls, but its impact can be even more noticeable in an application using streaming SSR as the App Router does. This is because the server can begin streaming content to the client, bringing even greater performance benefits.

Error handling

In a purely client-rendered app, errors thrown in components are always caught and displayed by the closest error boundary.

Errors thrown on the server when using one of the streaming server rendering APIs are treated differently. See the React documentation for more information.

Further reading

To view a larger codebase that makes use of Apollo Client's Suspense hooks (and many other new features introduced in Apollo Client 3.8), check out Apollo's Spotify Showcase on GitHub. It's a full-stack web application that pays homage to Spotify's iconic UI by building a clone using Apollo Client, Apollo Server and GraphOS.

useSuspenseQuery API

More details on useSuspenseQuery's API can be found in its API docs.

useBackgroundQuery API

More details on useBackgroundQuery's API can be found in its API docs.

useReadQuery API

More details on useReadQuery's API can be found in its API docs.