useInfiniteQuery<TData, TError, TPageParam> function

InfiniteQuerySnapshot<TData, TError, TPageParam> useInfiniteQuery<TData, TError, TPageParam>(List<Object?> queryKey, InfiniteQueryFn<TData, TPageParam> queryFn, { required TPageParam initialPageParam, required NextPageParamBuilder<TData, TPageParam> nextPageParamBuilder, PrevPageParamBuilder<TData, TPageParam>? prevPageParamBuilder, int? maxPages, bool? enabled, NetworkMode? networkMode, StaleDuration? staleDuration, GcDuration? gcDuration, Placeholder<InfiniteData<TData, TPageParam>>? placeholder, RefetchOnMount? refetchOnMount, RefetchOnResume? refetchOnResume, RefetchOnReconnect? refetchOnReconnect, Duration? refetchInterval, RetryResolver<TError>? retry, bool? retryOnMount, Seed<InfiniteData<TData, TPageParam>>? seed, SeedUpdatedAt? seedUpdatedAt, Map<String, dynamic>? meta, ShouldRebuild<InfiniteQuerySnapshot<TData, TError, TPageParam>>? shouldRebuild, QueryClient? client, })

A hook for fetching and caching paginated data with automatic page accumulation.

This hook extends useQuery with pagination support, managing multiple pages of data and providing methods to fetch additional pages in either direction.

The queryKey uniquely identifies this query in the cache. Queries with the same key share cached data across the widget tree.

The queryFn fetches a single page of data. It receives an InfiniteQueryFunctionContext containing the pageParam for the page to fetch.

Returns an InfiniteQuerySnapshot containing the accumulated pages, pagination state, and methods to fetch more pages: a sealed type supporting exhaustive pattern matching over InfiniteQueryPending / InfiniteQuerySuccess / InfiniteQueryError. The widget rebuilds automatically when the query state changes.

Options

• initialPageParam: The page parameter for the first page fetch.

• nextPageParamBuilder: A function that returns the page parameter for the next page, or null if there are no more pages. Receives the current InfiniteData containing all fetched pages.

• prevPageParamBuilder: A function that returns the page parameter for the previous page, or null if there are no previous pages. Required for bidirectional pagination.

• maxPages: The maximum number of pages to keep in cache. When exceeded, pages are removed from the opposite end of the fetch direction.

• enabled: Whether the query should execute. Defaults to true. Set to false to disable automatic fetching.

• networkMode: The network connectivity mode for this query. Has no effect unless connectivityChanges is provided to QueryClient.

  • NetworkMode.online (default): Pauses when offline, resumes when online
  • NetworkMode.always: Never pauses, ignores network state
  • NetworkMode.offlineFirst: First fetch runs regardless of network, retries pause when offline

• staleDuration: How long data remains fresh before becoming stale. Stale data may be refetched on the next access. Defaults to zero (data is immediately stale).

• gcDuration: How long unused data remains in cache before garbage collection. Defaults to 5 minutes.

• placeholder: Data to display while the query is pending and has no cached data. Unlike seed, placeholder data is not persisted to the cache. Provide the data directly with Placeholder.value, or lazily with Placeholder.lazy — the callback receives the data of the last query this hook had data for (e.g. before the query key changed) and may return null to show no placeholder. Use Placeholder.keepPrevious to keep showing the previous query's data while a new query key loads.

• refetchOnMount: Controls refetch behavior when this hook mounts. Can be RefetchOnMount.stale (default), RefetchOnMount.always, or RefetchOnMount.never.

• refetchOnResume: Controls refetch behavior when the app resumes from background. Can be RefetchOnResume.stale (default), RefetchOnResume.always, or RefetchOnResume.never.

• refetchOnReconnect: Controls refetch behavior when network connectivity is restored. Can be RefetchOnReconnect.stale (default), RefetchOnReconnect.always, or RefetchOnReconnect.never. Requires connectivityChanges to be provided to QueryClient.

• refetchInterval: Automatically refetch at the specified interval while this hook is mounted.

• retry: A callback that controls retry behavior on failure. Returns a Duration to retry after waiting, or null to stop retrying. Defaults to 3 retries with exponential backoff (1s, 2s, 4s).

• retryOnMount: Whether to retry failed queries when this hook mounts. Defaults to true.

• seed: Initial data to populate the cache before the first fetch. Unlike placeholder, seed data is persisted to the cache. Provide the data directly with Seed.value, or lazily with Seed.lazy — the callback may return null to skip seeding. A seed is applied only while the query has no data yet; cached data is never overwritten.

• seedUpdatedAt: The timestamp when seed data was last updated. Used to determine staleness of seed data. Provide it directly with SeedUpdatedAt.value, or lazily with SeedUpdatedAt.lazy.

• meta: A map of arbitrary metadata attached to this query, accessible in the query function context. When multiple hooks share the same query key, their meta maps are deep merged.

• shouldRebuild: An optional predicate that decides, per update, whether the widget rebuilds. Receives the last accepted result and the incoming result; return true to rebuild or false to suppress. When omitted, the widget rebuilds on every change.

• client: The QueryClient to use. If provided, takes precedence over the nearest QueryClientProvider ancestor.

See also:

• useQuery for non-paginated data
• useMutation for create, update, and delete operations

Implementation

InfiniteQuerySnapshot<TData, TError, TPageParam>
    useInfiniteQuery<TData, TError, TPageParam>(
  List<Object?> queryKey,
  InfiniteQueryFn<TData, TPageParam> queryFn, {
  required TPageParam initialPageParam,
  required NextPageParamBuilder<TData, TPageParam> nextPageParamBuilder,
  PrevPageParamBuilder<TData, TPageParam>? prevPageParamBuilder,
  int? maxPages,
  bool? enabled,
  NetworkMode? networkMode,
  StaleDuration? staleDuration,
  GcDuration? gcDuration,
  Placeholder<InfiniteData<TData, TPageParam>>? placeholder,
  RefetchOnMount? refetchOnMount,
  RefetchOnResume? refetchOnResume,
  RefetchOnReconnect? refetchOnReconnect,
  Duration? refetchInterval,
  RetryResolver<TError>? retry,
  bool? retryOnMount,
  Seed<InfiniteData<TData, TPageParam>>? seed,
  SeedUpdatedAt? seedUpdatedAt,
  Map<String, dynamic>? meta,
  ShouldRebuild<InfiniteQuerySnapshot<TData, TError, TPageParam>>?
      shouldRebuild,
  QueryClient? client,
}) {
  return useInfiniteQueryOptions(
    InfiniteQueryOptions(
      queryKey,
      queryFn,
      initialPageParam: initialPageParam,
      nextPageParamBuilder: nextPageParamBuilder,
      prevPageParamBuilder: prevPageParamBuilder,
      maxPages: maxPages,
      enabled: enabled,
      networkMode: networkMode,
      staleDuration: staleDuration,
      gcDuration: gcDuration,
      placeholder: placeholder,
      refetchOnMount: refetchOnMount,
      refetchOnResume: refetchOnResume,
      refetchOnReconnect: refetchOnReconnect,
      refetchInterval: refetchInterval,
      retry: retry,
      retryOnMount: retryOnMount,
      seed: seed,
      seedUpdatedAt: seedUpdatedAt,
      meta: meta,
    ),
    shouldRebuild: shouldRebuild,
    client: client,
  );
}