Centralize infinite-query configuration
Several components use the same feed query.
TanStack · Function
infiniteQueryOptions
Build reusable, type-safe options for an infinite query. The returned query key carries the query's infinite-data and error types across TanStack Query APIs.
How it works
Use infiniteQueryOptions to package an infinite query's key and behavior once, then reuse the returned options with TanStack Query APIs. Its return type brands the query key with the query's InfiniteData and error types, improving type inference when the key is passed elsewhere.
Syntax
infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options: UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;Parameters
| Name | Type | Description |
|---|---|---|
options | InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> | Infinite-query options to preserve and brand, including the query key and infinite-query behavior. |
Returns
The supplied infinite-query options, augmented with a query key branded with InfiniteData<TQueryFnData> and TError.
Key points
- The helper brands the query key so infinite-data and error types travel with it when the key is reused.
- Five generic type parameters describe page data, errors, selected data, the query key, and page parameters.
- The maxPages option limits how many pages remain in cached infinite-query data.
Common mistakes
- If you configure maxPages, older pages may be removed as new pages are fetched, so code should not assume every fetched page remains stored.
Example: Reusable infinite-query options
import { infiniteQueryOptions } from '@tanstack/react-query'
const feedOptions = infiniteQueryOptions({
queryKey: ['feed'],
initialPageParam: 0,
queryFn: ({ pageParam }) =>
fetch(`/api/feed?page=${pageParam}`).then((r) => r.json()),
getNextPageParam: (lastPage) => lastPage.nextCursor,
})
// feedOptions can be passed to useInfiniteQuery or queryClient methods.This helper accepts the configuration for an infinite query and returns it with an enriched query key. That branding lets TanStack Query preserve the infinite data and error types when the options are reused across its APIs.
When to use it
Preserve key-based type inference
A query key is passed to query-client APIs after being defined.
Configure paginated loading
A screen fetches successive cursor- or offset-based pages.
Interview questions
QWhat does infiniteQueryOptions do?
It is a type-safe builder for infinite-query configuration. The returned value brands its query key with InfiniteData and the error type, so reused keys retain useful type information across TanStack Query APIs.
Follow-up: Why does the helper return a branded key rather than only the input object? The branding allows APIs receiving the key to infer the corresponding infinite data and error types.
QWhat is the purpose of the options parameter and return value?
The options parameter contains the infinite-query configuration, including the query key, page parameter setup, query function, and page-navigation logic. Its return value is the supplied options augmented with query-key data branding.
Follow-up: How would you make the options reusable? Define them once with infiniteQueryOptions, then pass the returned object to useInfiniteQuery or compatible query-client operations.
QHow does this relate to paginated data?
Infinite query data represents all fetched pages together with their page parameters. The query function receives the page parameter for the page being fetched, while getNextPageParam determines the next page parameter.
Follow-up: What trade-off does maxPages introduce? It bounds retained memory by removing pages, so navigation or rendering logic must tolerate pages no longer being present.
Related
useInfiniteQueryInfiniteQueryOptionsInfiniteDataQueryKeyWithDataTagUseInfiniteQueryOptions