Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

queryOptions.md

304 lines11.3 KB

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:141](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L141)
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 known to be defined, so the resulting `data` is never
39`undefined` (unless a `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` known to be defined.
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 )
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:180](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L180)
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>
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:241](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L241)
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>
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>
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.