useSuspenseInfiniteQuery

React hook for fetching infinite data with Suspense support

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.