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

createInfiniteQuery.md

264 lines8.8 KB

1---
2id: createInfiniteQuery
3title: createInfiniteQuery
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8```ts
9const createInfiniteQuery: {
10<TQueryFnData, TError, TData, TQueryKey, TPageParam> (options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): DefinedUseInfiniteQueryResult<TData, TError>;
11<TQueryFnData, TError, TData, TQueryKey, TPageParam> (options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): UseInfiniteQueryResult<TData, TError>;
12} = useInfiniteQuery;
13```
14​
15Defined in: [packages/solid-query/src/index.ts:72](https://github.com/TanStack/query/blob/main/packages/solid-query/src/index.ts#L72)
16​
17## Call Signature
18​
19```ts
20<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): DefinedUseInfiniteQueryResult<TData, TError>;
21```
22​
23The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
24`initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
25​
26This overload is selected when `initialData` is known to be defined.
27​
28### Type Parameters
29​
30#### TQueryFnData
31​
32`TQueryFnData`
33​
34#### TError
35​
36`TError` = `Error`
37​
38#### TData
39​
40`TData` = [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>
41​
42#### TQueryKey
43​
44`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
45​
46#### TPageParam
47​
48`TPageParam` = `unknown`
49​
50### Parameters
51​
52#### options
53​
54[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
55​
56An accessor returning the [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfiniteOptions.md) to use β€” everything
57you can pass to `useInfiniteQuery`, with `initialData` known to be defined.
58​
59#### queryClient?
60​
61`Accessor`\<[`QueryClient`](../classes/QueryClient.md)\>
62​
63An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
64will be used.
65​
66### Returns
67​
68[`DefinedUseInfiniteQueryResult`](../type-aliases/DefinedUseInfiniteQueryResult.md)\<`TData`, `TError`\>
69​
70The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
71`hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
72`data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
73`InfiniteData<TQueryFnData>` shape.
74​
75### Remarks
76​
77Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
78refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
79actions, or add conditions like `hasNextPage && !isFetching`.
80​
81### See
82​
83[infiniteQueryOptions](../functions/infiniteQueryOptions.md) to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
84​
85### Example
86​
87```tsx
88import { For } from 'solid-js'
89import { useInfiniteQuery } from '@tanstack/solid-query'
90​
91function Projects() {
92 // `projectsQuery.data` is never `undefined`, thanks to `initialData` β€” even if a refetch fails, so the
93 // list stays visible alongside the error.
94 const projectsQuery = useInfiniteQuery(() => ({
95 queryKey: ['projects'],
96 queryFn: ({ pageParam }) => fetchProjects(pageParam),
97 initialPageParam: 0,
98 getNextPageParam: (lastPage) => lastPage.nextId,
99 initialData: { pages: [], pageParams: [] },
100 }))
101​
102 return (
103 <div>
104 {projectsQuery.isError ? <span>Error: {projectsQuery.error.message}</span> : null}
105 <ul>
106 <For each={projectsQuery.data.pages}>
107 {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
108 </For>
109 </ul>
110 </div>
111 )
113```
114​
115## Call Signature
116​
117```ts
118<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): UseInfiniteQueryResult<TData, TError>;
119```
120​
121The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
122`initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
123​
124### Type Parameters
125​
126#### TQueryFnData
127​
128`TQueryFnData`
129​
130#### TError
131​
132`TError` = `Error`
133​
134#### TData
135​
136`TData` = [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>
137​
138#### TQueryKey
139​
140`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
141​
142#### TPageParam
143​
144`TPageParam` = `unknown`
145​
146### Parameters
147​
148#### options
149​
150[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
151​
152An accessor returning the [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use β€” everything
153you can pass to `useInfiniteQuery`.
154​
155#### queryClient?
156​
157`Accessor`\<[`QueryClient`](../classes/QueryClient.md)\>
158​
159An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
160will be used.
161​
162### Returns
163​
164[`UseInfiniteQueryResult`](../type-aliases/UseInfiniteQueryResult.md)\<`TData`, `TError`\>
165​
166The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
167`hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
168`data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
169`InfiniteData<TQueryFnData>` shape.
170​
171### Remarks
172​
173Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
174refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
175actions, or add conditions like `hasNextPage && !isFetching`.
176​
177### See
178​
179[infiniteQueryOptions](../functions/infiniteQueryOptions.md) to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
180​
181### Examples
182​
183Fetching the next page from a "Load More" button click:
184```tsx
185import { For, Match, Switch } from 'solid-js'
186import { useInfiniteQuery } from '@tanstack/solid-query'
187​
188function Projects() {
189 const projectsQuery = useInfiniteQuery(() => ({
190 queryKey: ['projects'],
191 queryFn: ({ pageParam }) => fetchProjects(pageParam),
192 initialPageParam: 0,
193 getNextPageParam: (lastPage) => lastPage.nextId,
194 }))
195​
196 return (
197 <Switch>
198 <Match when={projectsQuery.isPending}>Loading...</Match>
199 <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
200 <Match when={projectsQuery.isSuccess}>
201 <ul>
202 <For each={projectsQuery.data.pages}>
203 {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
204 </For>
205 </ul>
206 <button
207 onClick={() => projectsQuery.fetchNextPage()}
208 disabled={!projectsQuery.hasNextPage || projectsQuery.isFetching}
209 >
210 {projectsQuery.isFetchingNextPage
211 ? 'Loading more...'
212 : projectsQuery.hasNextPage
213 ? 'Load More'
214 : 'Nothing more to load'}
215 </button>
216 </Match>
217 </Switch>
218 )
220```
221​
222Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
223sentinel element after the list:
224```tsx
225import { For, Match, Switch, createEffect, onCleanup } from 'solid-js'
226import { useInfiniteQuery } from '@tanstack/solid-query'
227​
228function Projects() {
229 const projectsQuery = useInfiniteQuery(() => ({
230 queryKey: ['projects'],
231 queryFn: ({ pageParam }) => fetchProjects(pageParam),
232 initialPageParam: 0,
233 getNextPageParam: (lastPage) => lastPage.nextId,
234 }))
235​
236 let sentinelRef: HTMLDivElement | undefined
237​
238 createEffect(() => {
239 if (sentinelRef == null || !projectsQuery.hasNextPage || projectsQuery.isFetching) return
240​
241 const observer = new IntersectionObserver(([entry]) => {
242 if (entry?.isIntersecting) projectsQuery.fetchNextPage()
243 })
244 observer.observe(sentinelRef)
245​
246 onCleanup(() => observer.disconnect())
247 })
248​
249 return (
250 <Switch>
251 <Match when={projectsQuery.isPending}>Loading...</Match>
252 <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
253 <Match when={projectsQuery.isSuccess}>
254 <ul>
255 <For each={projectsQuery.data.pages}>
256 {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
257 </For>
258 </ul>
259 <div ref={sentinelRef}>{projectsQuery.isFetchingNextPage ? 'Loading more...' : null}</div>
260 </Match>
261 </Switch>
262 )
264```