usePrefetchInfiniteQuery

React hook for prefetching infinite queries during render

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

TQueryFnData · type · default: "unknown"

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

TQueryKey · type · default: "QueryKey"

The type of the query key

TPageParam · type · default: "unknown"

The type of the page parameter

Parameters

options · FetchInfiniteQueryOptions · required

Configuration options for the infinite query to prefetch.

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.

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

getPreviousPageParam · (firstPage: TQueryFnData, allPages: TQueryFnData[], firstPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | undefined | null

Function that returns the previous page parameter

pages · number

Number of pages to prefetch. Defaults to 1.

queryClient · QueryClient

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.