Create a low-level infinite-query integration
Build framework adapters or custom hooks that need direct access to infinite-query observation.
TanStack · Class
InfiniteQueryObserver
InfiniteQueryObserver watches an infinite query and adds page-oriented state and methods to the base QueryObserver result. It is the core primitive behind framework-level infinite-query hooks.
How it works
InfiniteQueryObserver is the core observer for an infinite query. Construct it with a QueryClient and infinite-query options, subscribe to receive updated results, and use its page-fetching methods to load additional pages.
Syntax
new InfiniteQueryObserver<TQueryFnData, TError, TData, TQueryKey, TPageParam>(client: QueryClient, options: InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): InfiniteQueryObserver<TQueryFnData, TError, TData, TQueryKey, TPageParam>Parameters
| Name | Type | Description |
|---|---|---|
client | QueryClient | QueryClient used by the observer to access and manage the query cache. |
options | InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> | Configuration for the infinite query, including its key, query function, and page-parameter behavior. |
Returns
An InfiniteQueryObserver instance; its methods expose current results, subscriptions, and infinite-page fetching.
Key points
- It specializes QueryObserver for infinite-query data and lets an observer change the infinite query it watches.
- Results add infinite-query controls and state, including page availability and page-fetching operations.
- Framework integrations can implement higher-level infinite-query hooks on top of this core observer.
- The constructor receives a QueryClient plus typed infinite-query observer options and returns the configured observer.
- fetchNextPage() asynchronously loads the next page and resolves with the updated observer result.
- The current-result accessor provides the latest computed result available at the time it is called.
Common mistakes
- getCurrentResult() only returns a snapshot; use subscribe() when the code must react to later changes.
Example: Observe and fetch infinite-query pages
import { QueryClient } from '@tanstack/query-core'
import { InfiniteQueryObserver } from '@tanstack/query-core'
const client = new QueryClient()
const observer = new InfiniteQueryObserver(client, {
queryKey: ['posts'],
queryFn: async ({ pageParam }) =>
fetch(`/api/posts?cursor=${pageParam}`).then((r) => r.json()),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextCursor,
})
const unsubscribe = observer.subscribe((result) => {
console.log(result.data?.pages)
})
await observer.fetchNextPage()
unsubscribe()Creates an observer for cursor-based pages, listens for result updates, fetches the next page, and then unsubscribes.
When to use it
Subscribe to live query results
React to cache and fetch changes without repeatedly reading snapshots.
Fetch additional pages programmatically
Load cursor- or offset-based pages under application-controlled conditions.
Interview questions
QWhat is InfiniteQueryObserver used for?
It observes and switches between infinite queries while extending the normal query result with infinite-query capabilities such as page navigation. Framework adapters can build their infinite-query hooks on this primitive.
Follow-up: How would code react to asynchronous changes? Subscribe to the observer and process each emitted result; do not repeatedly poll a one-time result snapshot.
QHow is an InfiniteQueryObserver configured?
Construct it with a QueryClient and InfiniteQueryObserverOptions. The options define the query key, query function, initial page parameter, and how subsequent page parameters are derived.
Follow-up: Why is initialPageParam needed? It supplies the parameter for the first page, while later requests use values returned by the next- or previous-page parameter functions.
QHow does it load another page and expose updates?
fetchNextPage() requests the next page and returns a promise resolving to the resulting InfiniteQueryObserverResult. The result can expose infinite-query state such as whether another page exists.
Follow-up: What should happen after observing is no longer needed? Call the unsubscribe function returned by subscribe() to stop receiving updates.
Related
QueryObserverInfiniteQueryObserverOptionsInfiniteQueryResultQueryClientuseInfiniteQuery