0
Fork 0
mirror of https://github.com/TanStack/query.git synced 2026-11-16 22:50:20 +00:00
query/docs/framework/vue/reference/functions/queryOptions.md
Wonsuk Choi e57f8163b1
docs(query-core): add JSDoc across the package and expose it in generated reference docs (#11438)
* docs(query-core): add JSDoc across the package and expose it in generated reference docs

* docs(config.json): add sidebar entries for newly generated query-core reference docs

* docs(query-core): migrate remaining prose from the legacy 'docs/reference' pages into JSDoc

* docs(query-core): remove legacy 'docs/reference' pages superseded by the generated reference

* docs(query-core): regenerate reference docs after merging main

* docs(query-core): document missing default values for MutationOptions, combine, and QueryFilters.type

* fix(query-devtools): drop unnecessary 'query-core' project reference

* docs(query-core): document missing default values and normalize 'Defaults to' spacing

* docs(query-core): fix 'environmentManager' JSDoc example
2026-09-07 18:22:38 +02:00

8.6 KiB

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:168

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:205

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:250

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:316

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. This requires a whole-options getter: queryFn is a single value, not queryKey/enabled, so it isn't itself reactive — the getter is what re-evaluates it on every change to postId:

<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>