upstream-tanstack-query/docs/framework/react/reference/functions/useSuspenseQuery.md

id, title, redirect_from

id	title	redirect_from
useSuspenseQuery	useSuspenseQuery	framework/react/reference/useSuspenseQuery

function useSuspenseQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseSuspenseQueryResult<TData, TError>;

Defined in: packages/react-query/src/useSuspenseQuery.ts:75

The options for useSuspenseQuery are the same as for useQuery, except for throwOnError, enabled, and placeholderData — and queryFn may not be skipToken, since Suspense hooks can't render a "disabled" state.

Caveat: cancellation does not work.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>

The UseSuspenseQueryOptions to use — the same options as useQuery, minus the ones listed above.

queryClient?

QueryClient

Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns

UseSuspenseQueryResult<TData, TError>

The same object as useQuery, except that data is guaranteed to be defined, isPlaceholderData is missing, and status is either success or error (with the derived flags set accordingly).

Remarks

Multiple useSuspenseQuery calls in the same component suspend serially, causing a request waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until then. Use useSuspenseQueries instead when you have more than one suspenseful query in a component, so they fetch in parallel.

Example

The query error is thrown if the fetch fails and no cached data exists yet, so an error boundary is required around <Suspense>. A failed background refetch instead continues to render the cached data. Use QueryErrorResetBoundary to let the user retry after such an error:

import { Suspense } from 'react'
import { ErrorBoundary } from 'react-error-boundary'
import { QueryErrorResetBoundary, useSuspenseQuery } from '@tanstack/react-query'

function Posts() {
  // `data` is guaranteed to be defined here — no `isPending` check needed.
  const { data, isFetching } = useSuspenseQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  })

  return (
    <div>
      <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>
      <ul>
        {data.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  )
}

function App() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ resetErrorBoundary }) => (
            <div>
              There was an error!
              <button onClick={() => resetErrorBoundary()}>Try again</button>
            </div>
          )}
        >
          <Suspense fallback={<h1>Loading posts...</h1>}>
            <Posts />
          </Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  )
}