TanStack Query: Suspense Mode

TanStack Query: Suspense Mode

Use useSuspenseQuery to integrate React's Suspense and error boundaries with TanStack Query

When to Use

• Building components that should suspend while data loads rather than rendering a loading state inline
• Integrating TanStack Query with React 18 concurrent features and streaming SSR
• Eliminating loading state conditionals (if (isLoading) return <Spinner />) from components
• Coordinating multiple loading states with a single parent Suspense boundary
• Using TanStack Query with Next.js App Router streaming

Instructions

1. Use useSuspenseQuery instead of useQuery to opt into suspense mode — the component suspends instead of returning isLoading.
2. Wrap components using useSuspenseQuery in a <Suspense fallback={...}> boundary — without it, React throws an error.
3. Use useSuspenseQueries (plural) to run multiple suspense queries in parallel — suspends until all resolve.
4. Pair each <Suspense> with an error boundary (<ErrorBoundary> from react-error-boundary) to handle query errors.
5. Prefer useSuspenseQuery for data that is always needed — use regular useQuery for optional or conditional data.
6. For Next.js, prefetch data in Server Components and hydrate via <HydrationBoundary> — the Client Component suspends only if the cache is empty.

// With useSuspenseQuery — no loading conditional needed
'use client';
import { useSuspenseQuery } from '@tanstack/react-query';
import { postDetailOptions } from '@/queries/posts';

// This component either renders with data or suspends — never shows partial state
function PostContent({ id }: { id: string }) {
  const { data: post } = useSuspenseQuery(postDetailOptions(id));
  // data is guaranteed to be defined here — TypeScript knows this
  return <article>{post.content}</article>;
}

// Wrapping component manages the Suspense/Error boundaries
import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';

function PostPage({ id }: { id: string }) {
  return (
    <ErrorBoundary fallback={<PostError />}>
      <Suspense fallback={<PostSkeleton />}>
        <PostContent id={id} />
      </Suspense>
    </ErrorBoundary>
  );
}

// Multiple parallel suspense queries — waits for all
import { useSuspenseQueries } from '@tanstack/react-query';

function PostWithRelated({ id }: { id: string }) {
  const [{ data: post }, { data: related }] = useSuspenseQueries({
    queries: [
      postDetailOptions(id),
      relatedPostsOptions(id),
    ],
  });
  // Both are defined — component suspends until both resolve
  return <PostLayout post={post} related={related} />;
}

Details

useSuspenseQuery changes TanStack Query's data contract: instead of returning { data: T | undefined, isLoading, isError }, it returns { data: T } — data is always defined when the component renders. The component suspends (pauses rendering) until the data is available, and throws errors to the nearest error boundary.

Type safety improvement: With regular useQuery, data is typed as T | undefined — requiring null checks everywhere. With useSuspenseQuery, data is typed as T — no null checks needed because the component cannot render without data.

Suspense boundary placement: Multiple useSuspenseQuery calls in the same component all contribute to the same Suspense boundary. They suspend sequentially (each waits for the previous before starting) unless you use useSuspenseQueries which starts all fetches in parallel.

Sequential vs parallel suspension: Two useSuspenseQuery calls in one component create a waterfall — the second query does not start until the first resolves (because the component re-renders after each suspension). Use useSuspenseQueries to start all in parallel.

Error handling: useSuspenseQuery throws errors to the nearest React error boundary — unlike regular useQuery which catches errors internally and returns them as { isError, error }. Always pair <Suspense> with an <ErrorBoundary> when using suspense mode.

Next.js App Router: Suspense queries work naturally with Next.js streaming — the <Suspense> boundary streams its fallback first, then streams the resolved content. Combined with server-side prefetching via <HydrationBoundary>, the component only suspends on cold cache misses.

Source

https://tanstack.com/query/latest/docs/framework/react/guides/suspense

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.