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

useInfiniteQuery.md

73 lines4.3 KB

1---
2id: useInfiniteQuery
3title: useInfiniteQuery
4---
5​
6```tsx
7const {
8 fetchNextPage,
9 fetchPreviousPage,
10 hasNextPage,
11 hasPreviousPage,
12 isFetchingNextPage,
13 isFetchingPreviousPage,
14 ...result
15} = useInfiniteQuery({
16 queryKey,
17 queryFn: ({ pageParam = 1 }) => fetchPage(pageParam),
18 ...options,
19 getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
20 getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
21})
22```
23​
24**Options**
25​
26The options for `useInfiniteQuery` are identical to the [`useQuery` hook](../../../../framework/react/reference/useQuery) with the addition of the following:
27​
28- `queryFn: (context: QueryFunctionContext) => Promise<TData>`
29 - **Required, but only if no default query function has been defined** [`defaultQueryFn`](../../../../framework/react/guides/default-query-function)
30 - The function that the query will use to request data.
31 - Receives a [QueryFunctionContext](../../../../framework/react/guides/query-functions#queryfunctioncontext)
32 - Must return a promise that will either resolve data or throw an error.
33 - Make sure you return the data _and_ the `pageParam` if needed for use in the props below.
34- `getNextPageParam: (lastPage, allPages) => unknown | undefined`
35 - When new data is received for this query, this function receives both the last page of the infinite list of data and the full array of all pages.
36 - It should return a **single variable** that will be passed as the last optional parameter to your query function.
37 - Return `undefined` to indicate there is no next page available.
38- `getPreviousPageParam: (firstPage, allPages) => unknown | undefined`
39 - When new data is received for this query, this function receives both the first page of the infinite list of data and the full array of all pages.
40 - It should return a **single variable** that will be passed as the last optional parameter to your query function.
41 - Return `undefined` to indicate there is no previous page available.
42​
43**Returns**
44​
45The returned properties for `useInfiniteQuery` are identical to the [`useQuery` hook](../../../../framework/react/reference/useQuery), with the addition of the following and a small difference in `isRefetching`:
46​
47- `data.pages: TData[]`
48 - Array containing all pages.
49- `data.pageParams: unknown[]`
50 - Array containing all page params.
51- `isFetchingNextPage: boolean`
52 - Will be `true` while fetching the next page with `fetchNextPage`.
53- `isFetchingPreviousPage: boolean`
54 - Will be `true` while fetching the previous page with `fetchPreviousPage`.
55- `fetchNextPage: (options?: FetchNextPageOptions) => Promise<UseInfiniteQueryResult>`
56 - This function allows you to fetch the next "page" of results.
57 - `options.pageParam: unknown` allows you to manually specify a page param instead of using `getNextPageParam`.
58 - `options.cancelRefetch: boolean` if set to `true`, calling `fetchNextPage` repeatedly will invoke `fetchPage` every time, whether the previous
59 invocation has resolved or not. Also, the result from previous invocations will be ignored. If set to `false`, calling `fetchNextPage`
60 repeatedly won't have any effect until the first invocation has resolved. Default is `true`.
61- `fetchPreviousPage: (options?: FetchPreviousPageOptions) => Promise<UseInfiniteQueryResult>`
62 - This function allows you to fetch the previous "page" of results.
63 - `options.pageParam: unknown` allows you to manually specify a page param instead of using `getPreviousPageParam`.
64 - `options.cancelRefetch: boolean` same as for `fetchNextPage`.
65- `hasNextPage: boolean`
66 - This will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option).
67- `hasPreviousPage: boolean`
68 - This will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option).
69- `isRefetching: boolean`
70 - Is `true` whenever a background refetch is in-flight, which _does not_ include initial `loading` or fetching of next or previous page
71 - Is the same as `isFetching && !isLoading && !isFetchingNextPage && !isFetchingPreviousPage`
72​
73Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch behaviour, resulting in outdated data. Make sure to call these functions only in response to user actions, or add conditions like `hasNextPage && !isFetching`.