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

injectQuery.md

294 lines10.0 KB

1---
2id: injectQuery
3title: injectQuery
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8## Overview
9​
10```ts
11function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(optionsFn: () => DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedCreateQueryResult<TData, TError>;
12function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(optionsFn: () => UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): CreateQueryResult<TData, TError>;
13function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(optionsFn: () => CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>): CreateQueryResult<TData, TError>;
14```
15​
16- [`() => DefinedInitialDataOptions` β†’ `DefinedCreateQueryResult`](#call-signature-1): This overload is selected when `initialData` is known to be defined on the options returned by `optionsFn`, so the resulting `data` signal is never `undefined` (unless a `select` changes `TData` to include `undefined`).
17- [`() => UndefinedInitialDataOptions` β†’ `CreateQueryResult`](#call-signature-2): Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
18- [`() => CreateQueryOptions` β†’ `CreateQueryResult`](#call-signature-3): This overload accepts the general [CreateQueryOptions](../type-aliases/CreateQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site β€” useful when wrapping `injectQuery` in your own helper function that forwards caller-provided options.
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 injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(optionsFn: () => DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedCreateQueryResult<TData, TError>;
28```
29​
30Defined in: [packages/angular-query/src/inject-query.ts:59](https://github.com/TanStack/query/blob/main/packages/angular-query/src/inject-query.ts#L59)
31​
32This overload is selected when `initialData` is known to be defined on the options returned by `optionsFn`, so the
33resulting `data` signal is never `undefined` (unless a `select` changes `TData` to include `undefined`).
34​
35### Type Parameters
36​
37#### TQueryFnData
38​
39`TQueryFnData` = `unknown`
40​
41#### TError
42​
43`TError` = `Error`
44​
45#### TData
46​
47`TData` = `TQueryFnData`
48​
49#### TQueryKey
50​
51`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
52​
53### Parameters
54​
55#### optionsFn
56​
57() => [`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
58​
59A function returning the [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use β€” everything you
60can pass to `injectQuery`, with `initialData` known to be defined. Similar to `computed` from Angular, this function runs
61in the reactive context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive the query.
62​
63### Returns
64​
65[`DefinedCreateQueryResult`](../type-aliases/DefinedCreateQueryResult.md)\<`TData`, `TError`\>
66​
67The query result, typed so that `data` is never `undefined` (unless a `select` changes `TData` to
68include `undefined`). At runtime, `data` is still `undefined` if `select` throws on its first call.
69​
70### See
71​
72 - https://tanstack.com/query/latest/docs/framework/angular/guides/queries
73 - [queryOptions](queryOptions.md) to share these options between `injectQuery` and imperative APIs like
74`queryClient.query`.
75​
76### Example
77​
78```angular-ts
79@Component({
80 selector: 'posts',
81 template: `
82 <!-- `postsQuery.data()` is `Post[]`, never `undefined`, thanks to `initialData` β€” even if a
83 refetch fails, so the list stays visible alongside the error. -->
84 @if (postsQuery.isError()) {
85 <span>Error: {{ postsQuery.error()?.message }}</span>
86 }
87 <ul>
88 @for (post of postsQuery.data(); track post.id) {
89 <li>{{ post.title }}</li>
90 }
91 </ul>
92 `,
93})
94export class Posts {
95 readonly postsQuery = injectQuery(() => ({
96 queryKey: ['posts'],
97 queryFn: fetchPosts,
98 initialData: [],
99 }))
101```
102​
103<a id="call-signature-2"></a>
104​
105## Call Signature
106​
107```ts
108function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(optionsFn: () => UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): CreateQueryResult<TData, TError>;
109```
110​
111Defined in: [packages/angular-query/src/inject-query.ts:144](https://github.com/TanStack/query/blob/main/packages/angular-query/src/inject-query.ts#L144)
112​
113Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
114​
115### Type Parameters
116​
117#### TQueryFnData
118​
119`TQueryFnData` = `unknown`
120​
121#### TError
122​
123`TError` = `Error`
124​
125#### TData
126​
127`TData` = `TQueryFnData`
128​
129#### TQueryKey
130​
131`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
132​
133### Parameters
134​
135#### optionsFn
136​
137() => [`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
138​
139A function returning the [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use β€” everything
140you can pass to `injectQuery`. Similar to `computed` from Angular, this function runs in the reactive
141context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive the query.
142​
143### Returns
144​
145[`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\>
146​
147The query result. `status()` is `'error'` if the query has an error from a fetch that failed
148after its retries or if `select` threw, `'success'` if the query has cached data (even if `select`
149returns `undefined`) or data from `placeholderData`, and `'pending'` otherwise.
150`isPending`/`isSuccess`/`isError` are type-guard methods for convenience.
151​
152### See
153​
154 - https://tanstack.com/query/latest/docs/framework/angular/guides/queries
155 - [queryOptions](queryOptions.md) to share these options between `injectQuery` and imperative APIs like
156`queryClient.query`.
157​
158### Examples
159​
160```angular-ts
161@Component({
162 selector: 'posts',
163 template: `
164 @if (postsQuery.isPending()) {
165 Loading...
166 } @else if (postsQuery.isError()) {
167 <span>Error: {{ postsQuery.error()?.message }}</span>
168 } @else {
169 <ul>
170 @for (post of postsQuery.data(); track post.id) {
171 <li>{{ post.title }}</li>
172 }
173 </ul>
174 }
175 `,
176})
177export class Posts {
178 readonly postsQuery = injectQuery(() => ({
179 queryKey: ['posts'],
180 queryFn: fetchPosts,
181 }))
183```
184​
185Similar to `computed` from Angular, the function passed to `injectQuery` runs in the reactive context. In
186the example below, the query is automatically enabled and executed when the filter signal changes to a
187truthy value. When the filter signal changes back to a falsy value, the query is disabled.
188```angular-ts
189@Component({
190 selector: 'posts',
191 template: `
192 <input [ngModel]="filter()" (ngModelChange)="filter.set($event)" />
193 @if (postsQuery.isPending()) {
194 Loading...
195 } @else if (postsQuery.isError()) {
196 <span>Error: {{ postsQuery.error()?.message }}</span>
197 } @else {
198 <ul>
199 @for (post of postsQuery.data(); track post.id) {
200 <li>{{ post.title }}</li>
201 }
202 </ul>
203 }
204 `,
205})
206export class Posts {
207 readonly filter = signal('')
208​
209 readonly postsQuery = injectQuery(() => ({
210 queryKey: ['posts', this.filter()],
211 queryFn: () => fetchPosts(this.filter()),
212 // Signals can be combined with expressions
213 enabled: !!this.filter(),
214 }))
216```
217​
218<a id="call-signature-3"></a>
219​
220## Call Signature
221​
222```ts
223function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(optionsFn: () => CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>): CreateQueryResult<TData, TError>;
224```
225​
226Defined in: [packages/angular-query/src/inject-query.ts:168](https://github.com/TanStack/query/blob/main/packages/angular-query/src/inject-query.ts#L168)
227​
228This overload accepts the general [CreateQueryOptions](../type-aliases/CreateQueryOptions.md) shape rather than the `initialData`-aware
229overloads above, so whether `data` is defined can't be inferred from the call site β€” useful when wrapping
230`injectQuery` in your own helper function that forwards caller-provided options.
231​
232### Type Parameters
233​
234#### TQueryFnData
235​
236`TQueryFnData` = `unknown`
237​
238#### TError
239​
240`TError` = `Error`
241​
242#### TData
243​
244`TData` = `TQueryFnData`
245​
246#### TQueryKey
247​
248`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
249​
250### Parameters
251​
252#### optionsFn
253​
254() => [`CreateQueryOptions`](../type-aliases/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
255​
256A function that returns query options. Similar to `computed` from Angular, this
257function runs in the reactive context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive
258the query.
259​
260### Returns
261​
262[`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\>
263​
264The query result.
265​
266### See
267​
268https://tanstack.com/query/latest/docs/framework/angular/guides/queries
269​
270<a id="parameters-summary"></a>
271​
272## Parameters
273​
274### optionsFn
275​
276() => [`CreateQueryOptions`](../type-aliases/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
277​
278A function that returns query options. Similar to `computed` from Angular, this
279function runs in the reactive context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive
280the query.
281​
282<a id="optionsFn-properties"></a>
283​
284#### `optionsFn` properties
285​
286Built from [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md#properties). See the type above for what it changes.
287​
288<a id="returns-summary"></a>
289​
290## Returns
291​
292[`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\>
293​
294The query result.