API Documentation / @pinia/colada / UseInfiniteQueryOptions

Interface: UseInfiniteQueryOptions<TData, TError, TPageParam, TDataInitial> ​

Experimental

Options for useInfiniteQuery.

See https://github.com/posva/pinia-colada/issues/178

Extends ​

• Omit<UseQueryOptions<UseInfiniteQueryData<TData, TPageParam>, TError, TDataInitial>, "query" | "key">

Type Parameters ​

TData ​

TData

TError ​

TError

TPageParam ​

TPageParam

TDataInitial ​

TDataInitial extends | UseInfiniteQueryData<TData, TPageParam> | undefined

Properties ​

autoRefetch? ​

optional autoRefetch: number | boolean | <T>(state) => number | boolean;

Experimental

Whether to enable auto refresh by default.

Default ​

false

Inherited from ​

Omit.autoRefetch

delay? ​

optional delay: number | false;

Experimental

Delay in milliseconds to wait before letting the asyncStatus become 'loading'. Set to false or 0 to disable. Requires the PiniaColadaDelay plugin.

Default ​

200

Inherited from ​

UseQueryOptions.delay

enabled? ​

optional enabled: MaybeRefOrGetter<boolean>;

Experimental

Whether the query should be enabled or not. If false, the query will not be executed until refetch() or refresh() is called. If it becomes true, the query will be refreshed.

Inherited from ​

UseQueryOptionsGlobal.enabled

gcTime? ​

optional gcTime: number | false;

Experimental

Time in ms after which, once the data is no longer being used, it will be garbage collected to free resources. Set to false to disable garbage collection.

Default ​

300_000 (5 minutes)

Inherited from ​

Omit.gcTime

getNextPageParam() ​

getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) => NoInfer<TPageParam> | null | undefined;

Experimental

Function to get the next page parameter based on the last page and all pages fetched so far. If it returns undefined or null, it will consider there are no more pages to fetch.

Parameters ​

lastPage ​

NoInfer<TData>

allPages ​

NoInfer<TData>[]

lastPageParam ​

NoInfer<TPageParam>

allPageParams ​

NoInfer<TPageParam>[]

Returns ​

NoInfer<TPageParam> | null | undefined

getPreviousPageParam()? ​

optional getPreviousPageParam: (firstPage, allPages, firstPageParam, allPageParams) => TPageParam | null | undefined;

Experimental

Function to get the previous page parameter based on the first page and all pages fetched so far. If it returns undefined or null, it will consider there are no more pages to fetch.

Parameters ​

firstPage ​

TData

allPages ​

TData[]

firstPageParam ​

TPageParam

allPageParams ​

TPageParam[]

Returns ​

TPageParam | null | undefined

initialData()? ​

optional initialData: () => TDataInitial;

Experimental

The data which is initially set to the query while the query is loading for the first time. Note: unlike with placeholderData, setting the initial data changes the state of the query (it will be set to success).

Returns ​

TDataInitial

See ​

placeholderData

Inherited from ​

Omit.initialData

initialDataUpdatedAt? ​

optional initialDataUpdatedAt: number | () => number;

Experimental

The timestamp (in milliseconds) when the initial data was last updated. This determines the staleness of the initialData. If not provided, defaults to Date.now() when initial data is set.

Default ​

Date.now() when initialData is used

Example ​

// Using a static timestamp
useQuery({
  key: ['user'],
  query: () => fetchUser(),
  initialData: () => cachedUser,
  initialDataUpdatedAt: 1234567890000
})

// Using a function
useQuery({
  key: ['user'],
  query: () => fetchUser(),
  initialData: () => cachedUser,
  initialDataUpdatedAt: () => Number(localStorage.getItem('userTimestamp'))
})

Inherited from ​

Omit.initialDataUpdatedAt

initialPageParam ​

initialPageParam: TPageParam | () => TPageParam;

Experimental

Initial page parameter or function returning it. It's passed to the query

key ​

key: MaybeRefOrGetter<EntryKey>;

Experimental

maxPages? ​

optional maxPages: number;

Experimental

Maximum number of pages to keep in the cache. Old pages will be removed from the cache when new pages are added. If not set, all pages will be kept.

meta? ​

optional meta: MaybeRefOrGetter<Record<string, unknown>>;

Experimental

Meta information associated with the query. Can be a raw object, a function returning the meta object, or a ref containing the meta object. The meta is resolved when the entry is created and stored in entry.meta.

Note: Meta is serialized during SSR, so it must be serializable (no functions, class instances, or circular references). You can also completely ignore it during SSR with a ternary: meta: import.meta.ev.SSR ? {} : actualMeta

Example ​

// SSR-safe: simple serializable data
useQuery({
  key: ['user', id],
  query: () => fetchUser(id),
  meta: { errorMessage: true }
})

// Using a function to compute meta
useQuery({
  key: ['user', id],
  query: () => fetchUser(id),
  meta: () => ({ timestamp: Date.now() })
})

// Skipping meta during SSR
useQuery({
  key: ['user', id],
  query: () => fetchUser(id),
  meta: {
    onError: import.meta.env.SSR ? undefined : ((err) => console.log('error'))
  }
})

Inherited from ​

Omit.meta

placeholderData? ​

optional placeholderData: 
  | NoInfer<TDataInitial>
  | NoInfer<UseInfiniteQueryData<TData, TPageParam>>
  | <T>(previousData) => 
  | NoInfer<TDataInitial>
  | NoInfer<UseInfiniteQueryData<TData, TPageParam>>
  | undefined;

Experimental

A placeholder data that is initially shown while the query is loading for the first time. This will also show the status as success until the query finishes loading (no matter the outcome of the query). Note: unlike with initialData, the placeholder does not change the cache state.

See ​

initialData

Inherited from ​

Omit.placeholderData

query() ​

query: (context) => Promise<TData>;

Experimental

The function that will be called to fetch the data. It must be async.

Parameters ​

context ​

UseInfiniteQueryFnContext<UseInfiniteQueryData<unknown, TPageParam>, TError, TDataInitial, TPageParam>

Returns ​

Promise<TData>

refetchOnMount? ​

optional refetchOnMount: MaybeRefOrGetter<RefetchOnControl>;

Experimental

Whether to refetch the query when the component is mounted.

Default ​

true

Inherited from ​

UseQueryOptionsGlobal.refetchOnMount

refetchOnReconnect? ​

optional refetchOnReconnect: MaybeRefOrGetter<RefetchOnControl>;

Experimental

Whether to refetch the query when the network reconnects.

Default ​

true

Inherited from ​

UseQueryOptionsGlobal.refetchOnReconnect

refetchOnWindowFocus? ​

optional refetchOnWindowFocus: MaybeRefOrGetter<RefetchOnControl>;

Experimental

Whether to refetch the query when the window regains focus.

Default ​

true

Inherited from ​

UseQueryOptionsGlobal.refetchOnWindowFocus

retry? ​

optional retry: 
  | number
  | RetryOptions
  | (failureCount, error) => boolean;

Experimental

Options for the retries of this query added by @pinia/colada-plugin-retry.

Inherited from ​

Omit.retry

ssrCatchError? ​

optional ssrCatchError: boolean;

Experimental

Whether to catch errors during SSR (onServerPrefetch) when the query fails.

Default ​

false

Inherited from ​

UseQueryOptionsGlobal.ssrCatchError

staleTime? ​

optional staleTime: number;

Experimental

Time in ms after which the data is considered stale and will be refreshed on next read.

Default ​

5000 (5 seconds)

Inherited from ​

UseQueryOptionsGlobal.staleTime