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

queryOptions.md

330 lines11.5 KB

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