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

infiniteQueryOptions.md

314 lines12.5 KB

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