@apollo/client/skills/apollo-client/references/suspense-hooks.md

A fully-featured caching GraphQL client.

# Suspense Hooks Reference

> **Note**: Suspense hooks are the recommended approach for data fetching in modern React applications (React 18+). They provide cleaner code, better loading state handling, and enable streaming SSR.

## Table of Contents

- [useSuspenseQuery Hook](#usesuspensequery-hook)
- [useBackgroundQuery and useReadQuery](#usebackgroundquery-and-usereadquery)
- [useLoadableQuery](#useloadablequery)
- [createQueryPreloader](#createquerypreloader)
- [useQueryRefHandlers](#usequeryrefhandlers)
- [Distinguishing Queries with queryKey](#distinguishing-queries-with-querykey)
- [Suspense Boundaries and Error Handling](#suspense-boundaries-and-error-handling)
- [Transitions](#transitions)
- [Avoiding Request Waterfalls](#avoiding-request-waterfalls)
- [Fetch Policies](#fetch-policies)
- [Streaming SSR or React Server Components](#streaming-ssr-or-react-server-components)
- [Conditional Queries](#conditional-queries)

## useSuspenseQuery Hook

The `useSuspenseQuery` hook is the Suspense-ready replacement for `useQuery`. It initiates a network request and causes the component calling it to suspend while the request is made. Unlike `useQuery`, it does not return `loading` states—these are handled by React's Suspense boundaries and error boundaries.

### Basic Usage

```tsx
import { Suspense } from "react";
import { useSuspenseQuery } from "@apollo/client/react";
import { GET_DOG } from "./queries.generated";

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Dog id="3" />
    </Suspense>
  );
}

function Dog({ id }: { id: string }) {
  const { data } = useSuspenseQuery(GET_DOG, {
    variables: { id },
  });

  // data is always defined when this component renders
  return <div>Name: {data.dog.name}</div>;
}
```

### Return Object

```typescript
const {
  data, // Query result data
  dataState, // With default options: "complete" | "streaming"
  // With returnPartialData: also "partial"
  // With errorPolicy "all" or "ignore": also "empty"
  error, // ApolloError (only when errorPolicy is "all" or "ignore")
  networkStatus, // NetworkStatus.ready, NetworkStatus.loading, etc.
  client, // Apollo Client instance
  refetch, // Function to re-execute query
  fetchMore, // Function for pagination
} = useSuspenseQuery(QUERY, options);
```

### Key Differences from useQuery

- **No `loading` boolean**: Component suspends instead of returning `loading: true`
- **Error handling**: With default `errorPolicy` (`none`), errors are thrown and caught by error boundaries. With `errorPolicy: "all"` or `"ignore"`, the `error` property is returned and `data` may be `undefined`.
- **`data` availability**: With default `errorPolicy` (`none`), `data` is guaranteed to be present when the component renders. With `errorPolicy: "all"` or `"ignore"`, when `dataState` is `empty`, `data` may be `undefined`.
- **Suspense boundaries**: Must wrap component with `<Suspense>` to handle loading state

### Changing Variables

When variables change, `useSuspenseQuery` automatically re-runs the query. If the data is not in the cache, the component suspends again.

```tsx
import { useState } from "react";
import { GET_DOGS } from "./queries.generated";

function DogSelector() {
  const { data } = useSuspenseQuery(GET_DOGS);
  const [selectedDog, setSelectedDog] = useState(data.dogs[0].id);

  return (
    <>
      <select
        value={selectedDog}
        onChange={(e) => setSelectedDog(e.target.value)}
      >
        {data.dogs.map((dog) => (
          <option key={dog.id} value={dog.id}>
            {dog.name}
          </option>
        ))}
      </select>
      <Suspense fallback={<div>Loading...</div>}>
        <Dog id={selectedDog} />
      </Suspense>
    </>
  );
}

function Dog({ id }: { id: string }) {
  const { data } = useSuspenseQuery(GET_DOG, {
    variables: { id },
  });

  return (
    <>
      <div>Name: {data.dog.name}</div>
      <div>Breed: {data.dog.breed}</div>
    </>
  );
}
```

### Rendering Partial Data

Use `returnPartialData` to render immediately with partial cache data instead of suspending. The component will still suspend if there is no data in the cache.

```tsx
function Dog({ id }: { id: string }) {
  const { data } = useSuspenseQuery(GET_DOG, {
    variables: { id },
    returnPartialData: true,
  });

  return (
    <>
      <div>Name: {data.dog?.name ?? "Unknown"}</div>
      {data.dog?.breed && <div>Breed: {data.dog.breed}</div>}
    </>
  );
}
```

## useBackgroundQuery and useReadQuery

Use `useBackgroundQuery` with `useReadQuery` to avoid request waterfalls by starting a query in a parent component and reading the result in a child component. This pattern enables the parent to start fetching data before the child component renders.

### Basic Usage

```tsx
import { Suspense } from "react";
import { useBackgroundQuery, useReadQuery } from "@apollo/client/react";

function Parent() {
  // Start fetching immediately
  const [queryRef] = useBackgroundQuery(GET_DOG, {
    variables: { id: "3" },
  });

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Child queryRef={queryRef} />
    </Suspense>
  );
}

function Child({ queryRef }: { queryRef: QueryRef<DogData> }) {
  // Read the query result
  const { data } = useReadQuery(queryRef);

  return <div>Name: {data.dog.name}</div>;
}
```

### When to Use

- **Avoiding waterfalls**: Start fetching data in a parent (preferably above a suspense boundary) before child components render
- **Preloading data**: Begin fetching before the component that needs the data is ready
- **Parallel queries**: Start multiple queries at once in a parent component

### Return Values

`useBackgroundQuery` returns a tuple:

```typescript
const [
  queryRef, // QueryRef to pass to useReadQuery
  { refetch, fetchMore, subscribeToMore }, // Helper functions
] = useBackgroundQuery(QUERY, options);
```

`useReadQuery` returns the query result:

```typescript
const {
  data, // Query result data (always defined)
  dataState, // "complete" | "streaming" | "partial" | "empty"
  error, // ApolloError (if errorPolicy allows)
  networkStatus, // Detailed network state (1-8)
} = useReadQuery(queryRef);
```

## useLoadableQuery

Use `useLoadableQuery` to imperatively load a query in response to a user interaction (like a button click) instead of on component mount.

### Basic Usage

```tsx
import { Suspense } from "react";
import { useLoadableQuery, useReadQuery } from "@apollo/client/react";
import { GET_GREETING } from "./queries.generated";

function App() {
  const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);

  return (
    <>
      <button
        onClick={() => loadGreeting({ variables: { language: "english" } })}
      >
        Load Greeting
      </button>
      <Suspense fallback={<div>Loading...</div>}>
        {queryRef && <Greeting queryRef={queryRef} />}
      </Suspense>
    </>
  );
}

function Greeting({ queryRef }: { queryRef: QueryRef<GreetingData> }) {
  const { data } = useReadQuery(queryRef);

  return <div>{data.greeting.message}</div>;
}
```

### Return Values

```typescript
const [
  loadQuery, // Function to load the query
  queryRef, // QueryRef (null until loadQuery is called)
  { refetch, fetchMore, subscribeToMore, reset }, // Helper functions
] = useLoadableQuery(QUERY, options);
```

### When to Use

- **User-triggered fetching**: Load data in response to user actions
- **Lazy loading**: Defer data fetching until it's actually needed
- **Progressive disclosure**: Load data for UI elements that may not be initially visible

## createQueryPreloader

The `createQueryPreloader` function creates a `preloadQuery` function that can be used to initiate queries outside of React components. This is useful for preloading data before a component renders, such as in route loaders or event handlers.

### Basic Usage

```tsx
import { ApolloClient, InMemoryCache } from "@apollo/client";
import { createQueryPreloader } from "@apollo/client/react";

const client = new ApolloClient({
  uri: "https://your-graphql-endpoint.com/graphql",
  cache: new InMemoryCache(),
});

// Create a preload function
export const preloadQuery = createQueryPreloader(client);
```

### Using preloadQuery with Route Loaders

> **Note**: This example applies to React Router in non-framework mode. For React Router framework mode, see [integration-react-router.md](./integration-react-router.md).

Use the preload function with React Router's `loader` function to begin loading data during route transitions:

```tsx
import { preloadQuery } from "@/lib/apollo-client";
import { GET_DOG } from "./queries.generated";

// React Router loader function
export async function loader({ params }: { params: { id: string } }) {
  return preloadQuery({
    query: GET_DOG,
    variables: { id: params.id },
  });
}

// Route component
export default function DogRoute() {
  const queryRef = useLoaderData();

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <DogDetails queryRef={queryRef} />
    </Suspense>
  );
}

function DogDetails({ queryRef }: { queryRef: QueryRef<DogData> }) {
  const { data } = useReadQuery(queryRef);

  return (
    <div>
      <h1>{data.dog.name}</h1>
      <p>Breed: {data.dog.breed}</p>
    </div>
  );
}
```

### Preventing Route Transitions Until Query Loads

Use `preloadQuery.toPromise(queryRef)` to prevent route transitions until the query finishes loading:

```tsx
export async function loader({ params }: { params: { id: string } }) {
  const queryRef = preloadQuery({
    query: GET_DOG,
    variables: { id: params.id },
  });

  // Wait for the query to complete before transitioning
  return preloadQuery.toPromise(queryRef);
}
```

When `preloadQuery.toPromise()` is used, the route transition waits for the query to complete, and the data renders immediately without showing a loading fallback.

> **Note**: `preloadQuery.toPromise()` resolves with the `queryRef` itself (not the data) to encourage using `useReadQuery` for cache updates. If you need raw query data in your loader, use `client.query()` directly.

### With Next.js Server Components

> **Note**: For Next.js App Router, use the `PreloadQuery` component from `@apollo/client-integration-nextjs` instead. See [integration-nextjs.md](./integration-nextjs.md) for details.

## useQueryRefHandlers

The `useQueryRefHandlers` hook provides access to `refetch` and `fetchMore` functions for queries initiated with `preloadQuery`, `useBackgroundQuery`, or `useLoadableQuery`. This is useful when you need to refetch or paginate data in components where the `queryRef` is passed through.

> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.

### Basic Usage

```tsx
import { useQueryRefHandlers } from "@apollo/client/react";

function Breeds({ queryRef }: { queryRef: QueryRef<BreedsData> }) {
  const { refetch } = useQueryRefHandlers(queryRef);
  const { data } = useReadQuery(queryRef);
  const [isPending, startTransition] = useTransition();

  return (
    <div>
      <button
        disabled={isPending}
        onClick={() => {
          startTransition(() => {
            refetch();
          });
        }}
      >
        {isPending ? "Refetching..." : "Refetch breeds"}
      </button>
      <ul>
        {data.breeds.map((breed) => (
          <li key={breed.id}>{breed.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

### With Pagination

Use `fetchMore` to implement pagination:

```tsx
function Posts({ queryRef }: { queryRef: QueryRef<PostsData> }) {
  const { fetchMore } = useQueryRefHandlers(queryRef);
  const { data } = useReadQuery(queryRef);
  const [isPending, startTransition] = useTransition();

  return (
    <div>
      <ul>
        {data.posts.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
      <button
        disabled={isPending}
        onClick={() => {
          startTransition(() => {
            fetchMore({
              variables: {
                offset: data.posts.length,
              },
            });
          });
        }}
      >
        {isPending ? "Loading..." : "Load more"}
      </button>
    </div>
  );
}
```

### When to Use

- **Preloaded queries**: Access refetch/fetchMore for queries initiated with `preloadQuery`
- **Background queries**: Use in child components receiving `queryRef` from `useBackgroundQuery`
- **Loadable queries**: Refetch or paginate queries initiated with `useLoadableQuery`
- **React transitions**: Integrate with transitions to avoid showing loading fallbacks during refetches

## Distinguishing Queries with queryKey

Apollo Client uses the combination of `query` and `variables` to uniquely identify each query. When multiple components use the same `query` and `variables`, they share the same identity and suspend at the same time, regardless of which component initiates the request.

Use the `queryKey` option to ensure each hook has a unique identity:

```tsx
function UserProfile() {
  // First query with unique key
  const { data: userData } = useSuspenseQuery(GET_USER, {
    variables: { id: "1" },
    queryKey: ["user-profile"],
  });

  // Second query with same query and variables but different key
  const { data: userPreview } = useSuspenseQuery(GET_USER, {
    variables: { id: "1" },
    queryKey: ["user-preview"],
  });

  return (
    <div>
      <UserCard user={userData.user} />
      <UserSidebar user={userPreview.user} />
    </div>
  );
}
```

### When to Use

- **Multiple instances**: When rendering multiple components that use the same query and variables
- **Preventing shared suspension**: When you want independent control over when each query suspends
- **Separate cache entries**: When you need to maintain separate cache states for the same query

> **Note**: Each item in the `queryKey` array must be a stable identifier to prevent infinite fetches.

## Suspense Boundaries and Error Handling

### Suspense Boundaries

Wrap components that use Suspense hooks with `<Suspense>` boundaries to handle loading states. Place boundaries strategically to control the granularity of loading indicators.

```tsx
function App() {
  return (
    <>
      {/* Top-level loading for entire page */}
      <Suspense fallback={<PageSpinner />}>
        <Header />
        <Content />
      </Suspense>
    </>
  );
}

function Content() {
  return (
    <>
      <MainSection />
      {/* Granular loading for sidebar */}
      <Suspense fallback={<SidebarSkeleton />}>
        <Sidebar />
      </Suspense>
    </>
  );
}
```

### Error Boundaries

Suspense hooks throw errors to React error boundaries instead of returning them. Use error boundaries to handle GraphQL errors.

```tsx
import { ErrorBoundary } from "react-error-boundary";

function App() {
  return (
    <ErrorBoundary
      fallback={({ error }) => (
        <div>
          <h2>Something went wrong</h2>
          <p>{error.message}</p>
        </div>
      )}
    >
      <Suspense fallback={<div>Loading...</div>}>
        <Dog id="3" />
      </Suspense>
    </ErrorBoundary>
  );
}
```

### Custom Error Policies

Use `errorPolicy` to control how errors are handled:

```tsx
function Dog({ id }: { id: string }) {
  const { data, error } = useSuspenseQuery(GET_DOG, {
    variables: { id },
    errorPolicy: "all", // Return both data and errors
  });

  return (
    <>
      <div>Name: {data?.dog?.name ?? "Unknown"}</div>
      {error && <div>Warning: {error.message}</div>}
    </>
  );
}
```

## Transitions

Use React transitions to avoid showing loading UI when updating state. Transitions keep the previous UI visible while new data is fetching.

### Using startTransition

```tsx
import { useState, Suspense, startTransition } from "react";

function DogSelector() {
  const { data } = useSuspenseQuery(GET_DOGS);
  const [selectedDog, setSelectedDog] = useState(data.dogs[0].id);

  return (
    <>
      <select
        value={selectedDog}
        onChange={(e) => {
          // Wrap state update in startTransition
          startTransition(() => {
            setSelectedDog(e.target.value);
          });
        }}
      >
        {data.dogs.map((dog) => (
          <option key={dog.id} value={dog.id}>
            {dog.name}
          </option>
        ))}
      </select>
      <Suspense fallback={<div>Loading...</div>}>
        <Dog id={selectedDog} />
      </Suspense>
    </>
  );
}
```

### Using useTransition

Use `useTransition` to get an `isPending` flag for visual feedback during transitions.

```tsx
import { useState, Suspense, useTransition } from "react";

function DogSelector() {
  const [isPending, startTransition] = useTransition();
  const { data } = useSuspenseQuery(GET_DOGS);
  const [selectedDog, setSelectedDog] = useState(data.dogs[0].id);

  return (
    <>
      <select
        style={{ opacity: isPending ? 0.5 : 1 }}
        value={selectedDog}
        onChange={(e) => {
          startTransition(() => {
            setSelectedDog(e.target.value);
          });
        }}
      >
        {data.dogs.map((dog) => (
          <option key={dog.id} value={dog.id}>
            {dog.name}
          </option>
        ))}
      </select>
      <Suspense fallback={<div>Loading...</div>}>
        <Dog id={selectedDog} />
      </Suspense>
    </>
  );
}
```

## Avoiding Request Waterfalls

Request waterfalls occur when a child component waits for the parent to finish rendering before it can start fetching its own data. Use `useBackgroundQuery` to start fetching child data earlier in the component tree.

> **Note**: When one query depends on the result of another query (e.g., the child query needs an ID from the parent query), the waterfall is unavoidable. The best solution is to restructure your schema to fetch all needed data in a single nested query.

### Example: Independent Queries

When queries don't depend on each other, use `useBackgroundQuery` to start them in parallel:

```tsx
const GET_USER = gql`
  query GetUser($id: String!) {
    user(id: $id) {
      id
      name
    }
  }
`;

const GET_POSTS = gql`
  query GetPosts {
    posts {
      id
      title
    }
  }
`;

function Parent() {
  // Both queries start immediately - no waterfall
  const [userRef] = useBackgroundQuery(GET_USER, {
    variables: { id: "1" },
  });

  const [postsRef] = useBackgroundQuery(GET_POSTS);

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <UserProfile queryRef={userRef} />
      <PostsList queryRef={postsRef} />
    </Suspense>
  );
}

function UserProfile({ queryRef }: { queryRef: QueryRef<UserData> }) {
  const { data } = useReadQuery(queryRef);

  return <div>User: {data.user.name}</div>;
}

function PostsList({ queryRef }: { queryRef: QueryRef<PostsData> }) {
  const { data } = useReadQuery(queryRef);

  return (
    <ul>
      {data.posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}
```

## Fetch Policies

Suspense hooks support most of the same fetch policies as `useQuery`, controlling how the query interacts with the cache. Note that `cache-only` and `standby` are not supported by Suspense hooks.

| Policy              | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `cache-first`       | Return cached data if available, otherwise fetch (default) |
| `cache-and-network` | Return cached data immediately, then fetch and update      |
| `network-only`      | Always fetch, update cache, ignore cached data             |
| `no-cache`          | Always fetch, never read or write cache                    |

### Usage Examples

```tsx
// Always fetch fresh data
const { data } = useSuspenseQuery(GET_NOTIFICATIONS, {
  fetchPolicy: "network-only",
});

// Prefer cached data
const { data } = useSuspenseQuery(GET_CATEGORIES, {
  fetchPolicy: "cache-first",
});

// Show cached data while fetching fresh data
const { data } = useSuspenseQuery(GET_POSTS, {
  fetchPolicy: "cache-and-network",
});
```

## Streaming SSR or React Server Components

Apollo Client integrates with modern React frameworks that support Streaming SSR and React Server Components. For detailed setup instructions specific to your framework, see:

- **Next.js App Router**: [integration-nextjs.md](./integration-nextjs.md) - Includes React Server Components, PreloadQuery component, and streaming SSR
- **React Router**: [integration-react-router.md](./integration-react-router.md) - Framework mode with SSR support
- **TanStack Start**: [integration-tanstack-start.md](./integration-tanstack-start.md) - Full-stack React framework with SSR

These guides cover:

- Framework-specific client setup and configuration
- Preloading queries for optimal performance
- Streaming SSR with `useBackgroundQuery` and Suspense
- Error handling in server-rendered environments

## Conditional Queries

### Using skipToken

Use `skipToken` to conditionally skip queries without TypeScript issues. When `skipToken` is used, the component won't suspend and `data` will be `undefined`.

```tsx
import { skipToken } from "@apollo/client";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }
`;

function UserProfile({ userId }: { userId: string | null }) {
  const { data, dataState } = useSuspenseQuery(
    GET_USER,
    !userId ? skipToken : (
      {
        variables: { id: userId },
      }
    )
  );

  if (dataState !== "complete") {
    return <p>Select a user</p>;
  }

  return <Profile user={data.user} />;
}
```

### Conditional Rendering

Alternatively, use conditional rendering to control when Suspense hooks are called. This provides better type safety and clearer component logic.

```tsx
function UserProfile({ userId }: { userId: string | null }) {
  if (!userId) {
    return <p>Select a user</p>;
  }

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <UserDetails userId={userId} />
    </Suspense>
  );
}

function UserDetails({ userId }: { userId: string }) {
  const { data } = useSuspenseQuery(GET_USER, {
    variables: { id: userId },
  });

  return <Profile user={data.user} />;
}
```

> **Note**: Using conditional rendering with `skipToken` provides better type safety and avoids issues with required variables. The `skip` option is deprecated in favor of `skipToken`.