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