API Documentation / @pinia/colada / DefineQueryOptionsTagged

Interface: DefineQueryOptionsTagged<TData, TError, TDataInitial>

Tagged version of DefineQueryOptions that includes a key with data type information.

Extends

• DefineQueryOptions<TData, TError, TDataInitial>

Type Parameters

TData

TData = unknown

TError

TError = ErrorDefault

TDataInitial

TDataInitial extends TData | undefined = undefined

Properties

autoRefetch?

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

Whether to enable auto refresh by default.

Default

false

Inherited from

DefineQueryOptions.autoRefetch

---

delay?

optional delay?: number | false;

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

Default

200

Inherited from

PiniaColadaDelayOptions.delay

---

enabled?

optional enabled?: boolean;

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;

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

DefineQueryOptions.gcTime

---

initialData?

optional initialData?: () => TDataInitial;

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

DefineQueryOptions.initialData

---

initialDataUpdatedAt?

optional initialDataUpdatedAt?: number | (() => number);

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

DefineQueryOptions.initialDataUpdatedAt

---

key

key: EntryKeyTagged<TData, TError, TDataInitial>;

The key used to identify the query. Array of primitives without reactive values or a reactive array or getter. It should be treaded as an array of dependencies of your queries, e.g. if you use the route.params.id property, it should also be part of the key:

import { useRoute } from 'vue-router'
import { useQuery } from '@pinia/colada'

const route = useRoute()
const { data } = useQuery({
  // pass a getter function (or computed, ref, etc.) to ensure reactivity
  key: () => ['user', route.params.id],
  query: () => fetchUser(route.params.id),
})

Overrides

DefineQueryOptions.key

---

meta?

optional meta?: Record<string, unknown>;

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

DefineQueryOptions.meta

---

placeholderData?

optional placeholderData?: 
  | NoInfer<TDataInitial>
  | NoInfer<TData>
  | ((...args) => NoInfer<TDataInitial> | NoInfer<TData> | undefined);

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

DefineQueryOptions.placeholderData

---

refetchOnMount?

optional refetchOnMount?: RefetchOnControl;

Whether to refetch the query when the component is mounted.

Default

true

Inherited from

UseQueryOptionsGlobal.refetchOnMount

---

refetchOnReconnect?

optional refetchOnReconnect?: RefetchOnControl;

Whether to refetch the query when the network reconnects.

Default

true

Inherited from

UseQueryOptionsGlobal.refetchOnReconnect

---

refetchOnWindowFocus?

optional refetchOnWindowFocus?: RefetchOnControl;

Whether to refetch the query when the window regains focus.

Default

true

Inherited from

UseQueryOptionsGlobal.refetchOnWindowFocus

---

retry?

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

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

Inherited from

DefineQueryOptions.retry

---

ssrCatchError?

optional ssrCatchError?: boolean;

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

Default

false

Inherited from

UseQueryOptionsGlobal.ssrCatchError

---

staleTime?

optional staleTime?: number;

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

Methods

query()

query(context): Promise<TData>;

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

Parameters

context

UseQueryFnContext<unknown, TError, TDataInitial>

Returns

Promise<TData>

Inherited from

DefineQueryOptions.query