usePrefetchInfiniteQuery
The usePrefetchInfiniteQuery hook allows you to prefetch an infinite query during component render. This is useful for prefetching paginated data that you know will be needed soon.
Import
import { usePrefetchInfiniteQuery } from '@tanstack/react-query'
Signature
function usePrefetchInfiniteQuery<
TQueryFnData = unknown,
TError = DefaultError,
TData = TQueryFnData,
TQueryKey extends QueryKey = QueryKey,
TPageParam = unknown,
>(
options: FetchInfiniteQueryOptions<
TQueryFnData,
TError,
TData,
TQueryKey,
TPageParam
>,
queryClient?: QueryClient,
): void
Type Parameters
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:"TQueryFnData"
The type of data after transformation
The type of the query key
The type of the page parameter
Parameters
options
FetchInfiniteQueryOptions
required
Configuration options for the infinite query to prefetch.A unique key for the query. Must be an array.
queryFn
QueryFunction<TQueryFnData, TQueryKey>
required
The function that will be called to fetch data.
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
getPreviousPageParam
(firstPage: TQueryFnData, allPages: TQueryFnData[], firstPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | undefined | null
Function that returns the previous page parameter
Number of pages to prefetch. Defaults to 1.
Optional QueryClient instance to use. If not provided, the context client is used.
Returns
This hook does not return anything (void). It only triggers a prefetch if the query does not already exist in the cache.
Examples
Basic Usage
import { usePrefetchInfiniteQuery } from '@tanstack/react-query'
function ProjectsLink() {
// Prefetch the first page of projects
usePrefetchInfiniteQuery({
queryKey: ['projects'],
queryFn: ({ pageParam }) => fetchProjects(pageParam),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextCursor,
})
return <Link to="/projects">View Projects</Link>
}
Prefetch Multiple Pages
import { usePrefetchInfiniteQuery } from '@tanstack/react-query'
function ProjectsLink() {
// Prefetch the first 3 pages
usePrefetchInfiniteQuery({
queryKey: ['projects'],
queryFn: ({ pageParam }) => fetchProjects(pageParam),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextCursor,
pages: 3,
})
return <Link to="/projects">View Projects</Link>
}
Conditional Prefetching
import { useState } from 'react'
import { usePrefetchInfiniteQuery } from '@tanstack/react-query'
function ProjectsLink() {
const [shouldPrefetch, setShouldPrefetch] = useState(false)
// Only prefetch when hovering
if (shouldPrefetch) {
usePrefetchInfiniteQuery({
queryKey: ['projects'],
queryFn: ({ pageParam }) => fetchProjects(pageParam),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextCursor,
})
}
return (
<Link
to="/projects"
onMouseEnter={() => setShouldPrefetch(true)}
>
View Projects
</Link>
)
}
With Custom Configuration
import { usePrefetchInfiniteQuery } from '@tanstack/react-query'
function ProjectsLink({ category }: { category: string }) {
usePrefetchInfiniteQuery({
queryKey: ['projects', category],
queryFn: ({ pageParam }) => fetchProjects(category, pageParam),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextCursor,
getPreviousPageParam: (firstPage) => firstPage.previousCursor,
staleTime: 5 * 60 * 1000, // 5 minutes
})
return <Link to={`/projects/${category}`}>View {category} Projects</Link>
}
Notes
- The hook only prefetches if the query doesn’t already exist in the cache (checked via
queryClient.getQueryState).
- This hook is designed to be used during render, making it safe to use in component bodies.
- By default, only the first page is prefetched. Use the
pages option to prefetch more pages.
- For event-based prefetching (like onClick), consider using
queryClient.prefetchInfiniteQuery directly instead.
- The prefetch is fire-and-forget; you don’t get access to the loading state or data.
- If you need to access the query state, use
useInfiniteQuery instead.