function useSuspenseQuery<TQueryFnData, TError, TData, TQueryKey>(options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: 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?#
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>
)
}