Open History to see the last commit
1---
2id: queryOptions
3title: queryOptions
4redirect_from:
5 - framework/react/reference/queryOptions
6---
7β
8<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
9β
10## Overview
11β
12```ts
13function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
14function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
15function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
16```
17β
18- [`DefinedInitialDataOptions` β `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): 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.
19- [`UnusedSkipTokenOptions` β `UnusedSkipTokenOptions & QueryKeyWithDataTag`](#call-signature-2): 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.
20- [`UndefinedInitialDataOptions` β `UndefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-3): 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.
21β
22See also: [Parameters](#parameters-summary) Β· [Returns](#returns-summary)
23β
24<a id="call-signature-1"></a>
25β
26## Call Signature
27β
28```ts
29function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
30```
31β
32Defined in: [packages/react-query/src/queryOptions.ts:138](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L138)
33β
34You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
35be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
36is the query key to generate options for.
37β
38This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless
39a `select` changes `TData` to include `undefined`).
40β
41### Type Parameters
42β
43#### TQueryFnData
44β
45`TQueryFnData` = `unknown`
46β
47#### TError
48β
49`TError` = `Error`
50β
51#### TData
52β
53`TData` = `TQueryFnData`
54β
55#### TQueryKey
56β
57`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
58β
59### Parameters
60β
61#### options
62β
63[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
64β
65The [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use β everything you can pass to `useQuery`, with `initialData` set.
66β
67### Returns
68β
69[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\>
70β
71The same options object, typed so that `queryKey` carries the inferred data type.
72β
73### See
74β
75 - [useQuery](useQuery.md) to run a query with these options.
76 - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
77β
78### Example
79β
80```tsx
81import { queryOptions, useQuery } from '@tanstack/react-query'
82β
83export const postsOptions = queryOptions({
84 queryKey: ['posts'],
85 queryFn: fetchPosts,
86 initialData: [],
87})
88β
89function Posts() {
90 // `data` is `Post[]`, never `undefined`, thanks to `initialData` β even if a refetch fails,
91 // so the list stays visible alongside the error.
92 const { data, isError, error } = useQuery(postsOptions)
93β
94 return (
95 <div>
96 {isError ? <span>Error: {error.message}</span> : null}
97 <ul>
98 {data.map((post) => <li key={post.id}>{post.title}</li>)}
99 </ul>
100 </div>
101 )
102}
103```
104β
105<a id="call-signature-2"></a>
106β
107## Call Signature
108β
109```ts
110function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
111```
112β
113Defined in: [packages/react-query/src/queryOptions.ts:177](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L177)
114β
115You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
116be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
117is the query key to generate options for.
118β
119### Type Parameters
120β
121#### TQueryFnData
122β
123`TQueryFnData` = `unknown`
124β
125#### TError
126β
127`TError` = `Error`
128β
129#### TData
130β
131`TData` = `TQueryFnData`
132β
133#### TQueryKey
134β
135`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
136β
137### Parameters
138β
139#### options
140β
141[`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
142β
143The [UnusedSkipTokenOptions](../type-aliases/UnusedSkipTokenOptions.md) to use β everything you can pass to `useQuery`.
144β
145### Returns
146β
147[`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\>
148β
149The same options object, typed so that `queryKey` carries the inferred data type.
150β
151### See
152β
153 - [useQuery](useQuery.md) to run a query with these options.
154 - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
155β
156### Example
157β
158A parameterized factory, so the same options object can be reused per `id`:
159```tsx
160import { queryOptions, useQuery } from '@tanstack/react-query'
161β
162export const postOptions = (id: string) =>
163 queryOptions({
164 queryKey: ['post', id],
165 queryFn: () => fetchPost(id),
166 })
167β
168function Post({ id }: { id: string }) {
169 const { data, isPending, isError, error } = useQuery(postOptions(id))
170β
171 if (isPending) return 'Loading...'
172 if (isError) return <span>Error: {error.message}</span>
173β
174 return <h1>{data.title}</h1>
175}
176```
177β
178<a id="call-signature-3"></a>
179β
180## Call Signature
181β
182```ts
183function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
184```
185β
186Defined in: [packages/react-query/src/queryOptions.ts:238](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L238)
187β
188You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
189be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
190is the query key to generate options for.
191β
192### Type Parameters
193β
194#### TQueryFnData
195β
196`TQueryFnData` = `unknown`
197β
198#### TError
199β
200`TError` = `Error`
201β
202#### TData
203β
204`TData` = `TQueryFnData`
205β
206#### TQueryKey
207β
208`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
209β
210### Parameters
211β
212#### options
213β
214[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
215β
216The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use β everything you can pass to `useQuery`.
217β
218### Returns
219β
220[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\>
221β
222The same options object, typed so that `queryKey` carries the inferred data type.
223β
224### Remarks
225β
226This is the only overload that accepts `queryFn: skipToken`, shown below.
227β
228### See
229β
230 - [useQuery](useQuery.md) to run a query with these options.
231 - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
232β
233### Examples
234β
235A parameterized factory, so the same options object can be reused per `id`:
236```tsx
237import { queryOptions, useQuery } from '@tanstack/react-query'
238β
239export const postOptions = (id: string) =>
240 queryOptions({
241 queryKey: ['post', id],
242 queryFn: () => fetchPost(id),
243 })
244β
245function Post({ id }: { id: string }) {
246 const { data, isPending, isError, error } = useQuery(postOptions(id))
247β
248 if (isPending) return 'Loading...'
249 if (isError) return <span>Error: {error.message}</span>
250β
251 return <h1>{data.title}</h1>
252}
253```
254β
255A factory that disables the query, type safe, until `postId` is set:
256```tsx
257import { queryOptions, skipToken, useQuery } from '@tanstack/react-query'
258β
259export const postOptions = (postId: number | undefined) =>
260 queryOptions({
261 queryKey: ['post', postId],
262 queryFn: postId != null ? () => fetchPost(postId) : skipToken,
263 })
264β
265function Post({ postId }: { postId: number | undefined }) {
266 const { data, isLoading, isError, error } = useQuery(postOptions(postId))
267β
268 if (postId == null) return 'Select a post'
269 if (isLoading) return 'Loading...'
270 if (isError) return <span>Error: {error.message}</span>
271β
272 return <h1>{data?.title}</h1>
273}
274```
275β
276<a id="parameters-summary"></a>
277β
278## Parameters
279β
280### options
281β
282[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
283β
284The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use β everything you can pass to `useQuery`.
285β
286<a id="options-properties"></a>
287β
288#### `options` properties
289β
290Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties). See the type above for what it changes.
291β
292<a id="returns-summary"></a>
293β
294## Returns
295β
296[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\>
297β
298The same options object, typed so that `queryKey` carries the inferred data type.
299β
300<a id="result-properties"></a>
301β
302### Result properties
303β
304Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes.