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

queryOptions.md

302 lines11.3 KB

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