snapshot of https://github.com/TanStack/query.git (main, 2026-09-16; blobs > 131072B omitted)

docs/framework/vue/reference/functions/queryOptions.md

@@ -0,0 +1,310 @@
+---
+id: queryOptions
+title: queryOptions
+---
+
+## Call Signature
+
+```ts
+function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;
+```
+
+Defined in: [packages/vue-query/src/queryOptions.ts:244](https://github.com/TanStack/query/blob/main/packages/vue-query/src/queryOptions.ts#L244)
+
+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`](../type-aliases/DefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
+
+The [DefinedInitialQueryOptions](../type-aliases/DefinedInitialQueryOptions.md) to use — everything you can pass to `useQuery`, with
+`initialData` set.
+
+### Returns
+
+[`DefinedInitialQueryOptionsWithDataTag`](../type-aliases/DefinedInitialQueryOptionsWithDataTag.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
+
+The same options object, typed so that `queryKey` carries the inferred data type.
+
+### See
+
+[useQuery](useQuery.md) to run a query with these options.
+
+### Example
+
+```vue
+<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
+
+```ts
+function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): () => DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;
+```
+
+Defined in: [packages/vue-query/src/queryOptions.ts:281](https://github.com/TanStack/query/blob/main/packages/vue-query/src/queryOptions.ts#L281)
+
+Same as the plain-object overload, but for options that close over reactive state (`ref`s 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`](../type-aliases/DefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
+
+A function returning the [DefinedInitialQueryOptions](../type-aliases/DefinedInitialQueryOptions.md) to use, re-evaluated on demand.
+
+### Returns
+
+A function that returns the same options object, typed so that `queryKey` carries the inferred data
+type.
+
+```ts
+(): DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;
+```
+
+#### Returns
+
+[`DefinedInitialQueryOptionsWithDataTag`](../type-aliases/DefinedInitialQueryOptionsWithDataTag.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
+
+### See
+
+[useQuery](useQuery.md) to run a query with these options.
+
+### Example
+
+```vue
+<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
+
+```ts
+function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;
+```
+
+Defined in: [packages/vue-query/src/queryOptions.ts:326](https://github.com/TanStack/query/blob/main/packages/vue-query/src/queryOptions.ts#L326)
+
+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`](../type-aliases/UndefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
+
+The [UndefinedInitialQueryOptions](../type-aliases/UndefinedInitialQueryOptions.md) to use — everything you can pass to `useQuery`.
+
+### Returns
+
+[`UndefinedInitialQueryOptionsWithDataTag`](../type-aliases/UndefinedInitialQueryOptionsWithDataTag.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
+
+The same options object, typed so that `queryKey` carries the inferred data type.
+
+### See
+
+[useQuery](useQuery.md) to run a query with these options.
+
+### Example
+
+A parameterized factory, so the same options object can be reused per `id`:
+```vue
+<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
+
+```ts
+function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): () => UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;
+```
+
+Defined in: [packages/vue-query/src/queryOptions.ts:392](https://github.com/TanStack/query/blob/main/packages/vue-query/src/queryOptions.ts#L392)
+
+Same as the plain-object overload, but for options that close over reactive state (`ref`s 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`](../type-aliases/UndefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
+
+A function returning the [UndefinedInitialQueryOptions](../type-aliases/UndefinedInitialQueryOptions.md) to use, re-evaluated on
+demand.
+
+### Returns
+
+A function that returns the same options object, typed so that `queryKey` carries the inferred
+data type.
+
+```ts
+(): UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;
+```
+
+#### Returns
+
+[`UndefinedInitialQueryOptionsWithDataTag`](../type-aliases/UndefinedInitialQueryOptionsWithDataTag.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
+
+### See
+
+[useQuery](useQuery.md) to run a query with these options.
+
+### Examples
+
+```vue
+<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:
+```vue
+<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>
+```