upstream-tanstack-query/docs/framework/vue/reference/functions/queryOptions.md

id, title

id	title
queryOptions	queryOptions

Call Signature

function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

Defined in: packages/vue-query/src/queryOptions.ts:244

You can generally pass everything to queryOptions that you can also pass to useQuery. These options can be shared across hooks and imperative APIs such as queryClient.query. options.queryKey is required and is the query key to generate options for.

This overload is selected when initialData is set, so the resulting data is never undefined.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

The DefinedInitialQueryOptions to use — everything you can pass to useQuery, with initialData set.

Returns

DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>

The same options object, typed so that queryKey carries the inferred data type.

See

useQuery to run a query with these options.

Example

<script setup lang="ts">
import { queryOptions, useQuery } from '@tanstack/vue-query'

const postsOptions = queryOptions({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  initialData: [],
})

// `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
// so the list stays visible alongside the error.
const { data, isError, error } = useQuery(postsOptions)
</script>

Call Signature

function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): () => DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

Defined in: packages/vue-query/src/queryOptions.ts:281

Same as the plain-object overload, but for options that close over reactive state (refs read inside the function body). Wrap them in a getter so queryClient methods like invalidateQueries/fetchQuery always read the current values instead of the ones captured when the options were created.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

() => DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

A function returning the DefinedInitialQueryOptions to use, re-evaluated on demand.

Returns

A function that returns the same options object, typed so that queryKey carries the inferred data type.

(): DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

Returns

DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>

See

useQuery to run a query with these options.

Example

<script setup lang="ts">
import { ref } from 'vue'
import { queryOptions, useQuery } from '@tanstack/vue-query'

const postId = ref(1)
const postOptions = queryOptions(() => ({
  queryKey: ['post', postId.value],
  queryFn: () => fetchPost(postId.value),
  initialData: { id: postId.value, title: '' },
}))

// Pass the getter itself, not `postOptions()`, so the query keeps reacting to `postId` changes.
const { data } = useQuery(postOptions)
</script>

Call Signature

function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

Defined in: packages/vue-query/src/queryOptions.ts:326

You can generally pass everything to queryOptions that you can also pass to useQuery. These options can be shared across hooks and imperative APIs such as queryClient.query. options.queryKey is required and is the query key to generate options for.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

The UndefinedInitialQueryOptions to use — everything you can pass to useQuery.

Returns

UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>

The same options object, typed so that queryKey carries the inferred data type.

See

useQuery to run a query with these options.

Example

A parameterized factory, so the same options object can be reused per id:

<script setup lang="ts">
import { queryOptions, useQuery } from '@tanstack/vue-query'

function postOptions(id: string) {
  return queryOptions({
    queryKey: ['post', id],
    queryFn: () => fetchPost(id),
  })
}

const { data, isPending, isError, error } = useQuery(postOptions('1'))
</script>

Call Signature

function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): () => UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

Defined in: packages/vue-query/src/queryOptions.ts:392

Same as the plain-object overload, but for options that close over reactive state (refs read inside the function body). Wrap them in a getter so the queryKey — and anything else derived from a ref — reacts to changes, and so queryClient methods like invalidateQueries/fetchQuery always read the current values instead of the ones captured when the options were created.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

() => UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

A function returning the UndefinedInitialQueryOptions to use, re-evaluated on demand.

Returns

A function that returns the same options object, typed so that queryKey carries the inferred data type.

(): UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

Returns

UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>

See

useQuery to run a query with these options.

Examples

<script setup lang="ts">
import { ref } from 'vue'
import { queryOptions, useQuery, useQueryClient } from '@tanstack/vue-query'

const postId = ref(1)
const postOptions = queryOptions(() => ({
  queryKey: ['post', postId.value],
  queryFn: () => fetchPost(postId.value),
}))

// Pass the getter itself, not `postOptions()`, so the query keeps reacting to `postId` changes.
const { data } = useQuery(postOptions)
const queryClient = useQueryClient()
// Here, call `postOptions()` so `invalidateQueries` reads the current `queryKey` right away.
queryClient.invalidateQueries(postOptions())
</script>

A parameterized factory that disables the query, type safe, until postId is set. The whole-options getter re-evaluates queryFn on every change to postId. queryFn can also be a computed, but never a bare getter, since a function there is the query function itself:

<script setup lang="ts">
import { queryOptions, skipToken, useQuery } from '@tanstack/vue-query'

function postOptions(postId: number | undefined) {
  return queryOptions(() => ({
    queryKey: ['post', postId],
    queryFn: postId != null ? () => fetchPost(postId) : skipToken,
  }))
}

const props = defineProps<{ postId: number | undefined }>()
const { data, isLoading, isError, error } = useQuery(postOptions(props.postId))
</script>