Skip to main content

​
useSuspenseInfiniteQuery

The useSuspenseInfiniteQuery hook is a Suspense-enabled version of useInfiniteQuery. It suspends rendering until data is available and always returns data (never undefined).

​
Import

import { useSuspenseInfiniteQuery } from '@tanstack/react-query'

​
Signature

function useSuspenseInfiniteQuery<
  TQueryFnData,
  TError = DefaultError,
  TData = InfiniteData<TQueryFnData>,
  TQueryKey extends QueryKey = QueryKey,
  TPageParam = unknown,
>(
  options: UseSuspenseInfiniteQueryOptions<
    TQueryFnData,
    TError,
    TData,
    TQueryKey,
    TPageParam
  >,
  queryClient?: QueryClient,
): UseSuspenseInfiniteQueryResult<TData, TError>

​
Type Parameters

​
TQueryFnData
type
The type of data returned by the query function for each page
​
TError
type
default:"DefaultError"
The type of error that can be thrown by the query function
​
TData
type
default:"InfiniteData<TQueryFnData>"
The type of data returned by the select function (if provided)
​
TQueryKey
type
default:"QueryKey"
The type of the query key
​
TPageParam
type
default:"unknown"
The type of the page parameter

​
Parameters

​
options
UseSuspenseInfiniteQueryOptions
required
Configuration options for the infinite query. All options from useInfiniteQuery are supported, with the following differences:
​
queryKey
TQueryKey
required
A unique key for the query. Must be an array.
​
queryFn
QueryFunction<TQueryFnData, TQueryKey>
required
The function that will be called to fetch data. Cannot use skipToken with Suspense queries.
​
initialPageParam
TPageParam
required
The default page param to use when fetching the first page
​
getNextPageParam
(lastPage: TQueryFnData, allPages: TQueryFnData[], lastPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | undefined | null
required
Function that returns the next page parameter. Return undefined or null to indicate there are no more pages.
​
getPreviousPageParam
(firstPage: TQueryFnData, allPages: TQueryFnData[], firstPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | undefined | null
Function that returns the previous page parameter. Return undefined or null to indicate there are no previous pages.
​
enabled
boolean
default:"true"
This option is always set to true for suspense queries
​
throwOnError
boolean | (error: TError) => boolean
default:"true"
Set to true to throw errors to the nearest error boundary
​
queryClient
QueryClient
Optional QueryClient instance to use. If not provided, the context client is used.

​
Returns

​
data
TData
required
The data returned by the query function. Always defined (never undefined) for suspense queries.
​
error
null
Always null for suspense queries (errors are thrown to error boundaries)
​
status
'success'
Always 'success' for suspense queries
​
fetchStatus
FetchStatus
The fetch status of the query: 'fetching', 'paused', or 'idle'
​
isSuccess
true
Always true for suspense queries
​
isPending
false
Always false for suspense queries
​
isError
false
Always false for suspense queries
​
isFetching
boolean
Whether the query is currently fetching
​
hasNextPage
boolean
Whether there is a next page available
​
hasPreviousPage
boolean
Whether there is a previous page available
​
fetchNextPage
(options?: FetchNextPageOptions) => Promise<InfiniteQueryObserverResult>
Function to fetch the next page
​
fetchPreviousPage
(options?: FetchPreviousPageOptions) => Promise<InfiniteQueryObserverResult>
Function to fetch the previous page
​
isFetchingNextPage
boolean
Whether the query is currently fetching the next page
​
isFetchingPreviousPage
boolean
Whether the query is currently fetching the previous page
​
refetch
(options?: RefetchOptions) => Promise<QueryObserverResult>
Function to manually refetch the query

​
Examples

​
Basic Usage

import { useSuspenseInfiniteQuery } from '@tanstack/react-query'

function Projects() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
  } = useSuspenseInfiniteQuery({
    queryKey: ['projects'],
    queryFn: async ({ pageParam }) => {
      const res = await fetch(`/api/projects?cursor=${pageParam}`)
      return res.json()
    },
    initialPageParam: 0,
    getNextPageParam: (lastPage) => lastPage.nextCursor,
  })

  return (
    <div>
      {data.pages.map((page) => (
        <div key={page.id}>
          {page.projects.map((project) => (
            <p key={project.id}>{project.name}</p>
          ))}
        </div>
      ))}
      <button
        onClick={() => fetchNextPage()}
        disabled={!hasNextPage || isFetchingNextPage}
      >
        {isFetchingNextPage
          ? 'Loading more...'
          : hasNextPage
            ? 'Load More'
            : 'Nothing more to load'}
      </button>
    </div>
  )
}

​
With Error Boundary

import { Suspense } from 'react'
import { ErrorBoundary } from 'react-error-boundary'
import { useSuspenseInfiniteQuery } from '@tanstack/react-query'

function App() {
  return (
    <ErrorBoundary fallback={<div>Something went wrong</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <Projects />
      </Suspense>
    </ErrorBoundary>
  )
}

function Projects() {
  const { data } = useSuspenseInfiniteQuery({
    queryKey: ['projects'],
    queryFn: fetchProjects,
    initialPageParam: 0,
    getNextPageParam: (lastPage) => lastPage.nextCursor,
  })

  // data is always defined here
  return <div>{/* render data */}</div>
}

​
Notes

  • skipToken cannot be used with useSuspenseInfiniteQuery. If you need conditional fetching, use useInfiniteQuery instead.
  • The component will suspend until the initial data is loaded.
  • Errors are thrown to the nearest error boundary by default.
  • The enabled option is always set to true and cannot be disabled.

Build docs developers (and LLMs) love

Get started for freeTalk to us