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

infiniteQueryOptions.md

316 lines13.2 KB

1---
2id: infiniteQueryOptions
3title: infiniteQueryOptions
4redirect_from:
5 - framework/react/reference/infiniteQueryOptions
6---
7​
8<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
9​
10## Overview
11​
12```ts
13function infiniteQueryOptions<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
14function infiniteQueryOptions<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
15function infiniteQueryOptions<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
16```
17​
18- [`DefinedInitialDataInfiniteOptions` β†’ `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for.
19- [`UnusedSkipTokenInfiniteOptions` β†’ `UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for.
20- [`UndefinedInitialDataInfiniteOptions` β†’ `UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `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 infiniteQueryOptions<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
30```
31​
32Defined in: [packages/react-query/src/infiniteQueryOptions.ts:165](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L165)
33​
34You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
35These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
36`options.queryKey` is required and is the query key to generate options for.
37​
38This overload is selected when `initialData` is set.
39​
40### Type Parameters
41​
42#### TQueryFnData
43​
44`TQueryFnData`
45​
46#### TError
47​
48`TError` = `Error`
49​
50#### TData
51​
52`TData` = [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>
53​
54#### TQueryKey
55​
56`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
57​
58#### TPageParam
59​
60`TPageParam` = `unknown`
61​
62### Parameters
63​
64#### options
65​
66[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
67​
68The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfiniteOptions.md) to use β€” everything you can pass to `useInfiniteQuery`, with `initialData` set.
69​
70### Returns
71​
72[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\>
73​
74The same options object, typed so that `queryKey` carries the inferred data type.
75​
76### Remarks
77​
78See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages, from a button click or
79automatically as the user scrolls.
80​
81### See
82​
83[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options.
84​
85### Example
86​
87```tsx
88import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-query'
89​
90export const projectsOptions = infiniteQueryOptions({
91 queryKey: ['projects'],
92 queryFn: ({ pageParam }) => fetchProjects(pageParam),
93 initialPageParam: 0,
94 getNextPageParam: (lastPage) => lastPage.nextId,
95 initialData: { pages: [], pageParams: [] },
96})
97​
98function Projects() {
99 // `data` is never `undefined`, thanks to `initialData` β€” even if a refetch fails, so the
100 // list stays visible alongside the error.
101 const { data, isError, error } = useInfiniteQuery(projectsOptions)
102​
103 return (
104 <div>
105 {isError ? <span>Error: {error.message}</span> : null}
106 <ul>
107 {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
108 </ul>
109 </div>
110 )
112```
113​
114<a id="call-signature-2"></a>
115​
116## Call Signature
117​
118```ts
119function infiniteQueryOptions<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
120```
121​
122Defined in: [packages/react-query/src/infiniteQueryOptions.ts:224](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L224)
123​
124You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
125These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
126`options.queryKey` is required and is the query key to generate options for.
127​
128### Type Parameters
129​
130#### TQueryFnData
131​
132`TQueryFnData`
133​
134#### TError
135​
136`TError` = `Error`
137​
138#### TData
139​
140`TData` = [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>
141​
142#### TQueryKey
143​
144`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
145​
146#### TPageParam
147​
148`TPageParam` = `unknown`
149​
150### Parameters
151​
152#### options
153​
154[`UnusedSkipTokenInfiniteOptions`](../type-aliases/UnusedSkipTokenInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
155​
156The [UnusedSkipTokenInfiniteOptions](../type-aliases/UnusedSkipTokenInfiniteOptions.md) to use β€” everything you can pass to `useInfiniteQuery`.
157​
158### Returns
159​
160[`UnusedSkipTokenInfiniteOptions`](../type-aliases/UnusedSkipTokenInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\>
161​
162The same options object, typed so that `queryKey` carries the inferred data type.
163​
164### Remarks
165​
166See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages, from a button click or
167automatically as the user scrolls.
168​
169### See
170​
171[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options.
172​
173### Example
174​
175A parameterized factory, so the same options object can be reused per `postId`:
176```tsx
177import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-query'
178​
179export const commentsOptions = (postId: string) =>
180 infiniteQueryOptions({
181 queryKey: ['post', postId, 'comments'],
182 queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
183 initialPageParam: 0,
184 getNextPageParam: (lastPage) => lastPage.nextId,
185 })
186​
187function Comments({ postId }: { postId: string }) {
188 const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
189​
190 if (isPending) return 'Loading...'
191 if (isError) return <span>Error: {error.message}</span>
192​
193 return (
194 <ul>
195 {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
196 </ul>
197 )
199```
200​
201<a id="call-signature-3"></a>
202​
203## Call Signature
204​
205```ts
206function infiniteQueryOptions<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
207```
208​
209Defined in: [packages/react-query/src/infiniteQueryOptions.ts:283](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L283)
210​
211You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
212These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
213`options.queryKey` is required and is the query key to generate options for.
214​
215### Type Parameters
216​
217#### TQueryFnData
218​
219`TQueryFnData`
220​
221#### TError
222​
223`TError` = `Error`
224​
225#### TData
226​
227`TData` = [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>
228​
229#### TQueryKey
230​
231`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
232​
233#### TPageParam
234​
235`TPageParam` = `unknown`
236​
237### Parameters
238​
239#### options
240​
241[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
242​
243The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use β€” everything you can pass to `useInfiniteQuery`.
244​
245### Returns
246​
247[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\>
248​
249The same options object, typed so that `queryKey` carries the inferred data type.
250​
251### Remarks
252​
253See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages (from a button click or
254automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set.
255​
256### See
257​
258[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options.
259​
260### Example
261​
262A parameterized factory, so the same options object can be reused per `postId`:
263```tsx
264import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/react-query'
265​
266export const commentsOptions = (postId: string) =>
267 infiniteQueryOptions({
268 queryKey: ['post', postId, 'comments'],
269 queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
270 initialPageParam: 0,
271 getNextPageParam: (lastPage) => lastPage.nextId,
272 })
273​
274function Comments({ postId }: { postId: string }) {
275 const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
276​
277 if (isPending) return 'Loading...'
278 if (isError) return <span>Error: {error.message}</span>
279​
280 return (
281 <ul>
282 {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
283 </ul>
284 )
286```
287​
288<a id="parameters-summary"></a>
289​
290## Parameters
291​
292### options
293​
294[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
295​
296The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use β€” everything you can pass to `useInfiniteQuery`.
297​
298<a id="options-properties"></a>
299​
300#### `options` properties
301​
302Built from [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md#properties). See the type above for what it changes.
303​
304<a id="returns-summary"></a>
305​
306## Returns
307​
308[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\>
309​
310The same options object, typed so that `queryKey` carries the inferred data type.
311​
312<a id="result-properties"></a>
313​
314### Result properties
315​
316Built from [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes.