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