Infinite Queries

Rendering lists that can additively "load more" data onto an existing set of data or "infinite scroll" is also a very common UI pattern. React Query supports a useful version of useQuery called useInfiniteQuery for querying these types of lists.

When using useInfiniteQuery, you'll notice a few things are different:

• data is now an array of arrays that contain query group results, instead of the query results themselves
• A fetchMore function is now available
• A getFetchMore option is available for both determining if there is more data to load and the information to fetch it. This information is supplied as an additional parameter in the query function (which can optionally be overridden when calling the fetchMore function)
• A canFetchMore boolean is now available and is true if getFetchMore returns a truthy value
• An isFetchingMore boolean is now available to distinguish between a background refresh state and a loading more state

Example

Let's assume we have an API that returns pages of projects 3 at a time based on a cursor index along with a cursor that can be used to fetch the next group of projects:

1 fetch('/api/projects?cursor=0')
2 // { data: [...], nextCursor: 3}
3 fetch('/api/projects?cursor=3')
4 // { data: [...], nextCursor: 6}
5 fetch('/api/projects?cursor=6')
6 // { data: [...], nextCursor: 9}
7 fetch('/api/projects?cursor=9')
8 // { data: [...] }

With this information, we can create a "Load More" UI by:

• Waiting for useInfiniteQuery to request the first group of data by default
• Returning the information for the next query in getFetchMore
• Calling fetchMore function

Note: It's very important you do not call fetchMore with arguments unless you want them to override the fetchMoreInfo data returned from the getFetchMore function. eg. Do not do this: <button onClick={fetchMore} /> as this would send the onClick event to the fetchMore function.

1 import { useInfiniteQuery } from 'react-query'
2 
3 function Projects() {
4   const fetchProjects = (key, cursor = 0) =>
5     fetch('/api/projects?cursor=' + cursor)
6 
7   const {
8     status,
9     data,
10     isFetching,
11     isFetchingMore,
12     fetchMore,
13     canFetchMore,
14   } = useInfiniteQuery('projects', fetchProjects, {
15     getFetchMore: (lastGroup, allGroups) => lastGroup.nextCursor,
16   })
17 
18   return status === 'loading' ? (
19     <p>Loading...</p>
20   ) : status === 'error' ? (
21     <p>Error: {error.message}</p>
22   ) : (
23     <>
24       {data.map((group, i) => (
25         <React.Fragment key={i}>
26           {group.projects.map(project => (
27             <p key={project.id}>{project.name}</p>
28           ))}
29         </React.Fragment>
30       ))}
31       <div>
32         <button
33           onClick={() => fetchMore()}
34           disabled={!canFetchMore || isFetchingMore}
35         >
36           {isFetchingMore
37             ? 'Loading more...'
38             : canFetchMore
39             ? 'Load More'
40             : 'Nothing more to load'}
41         </button>
42       </div>
43       <div>{isFetching && !isFetchingMore ? 'Fetching...' : null}</div>
44     </>
45   )
46 }

What happens when an infinite query needs to be refetched?

When an infinite query becomes stale and needs to be refetched, each group is fetched sequentially, starting from the first one. This ensures that even if the underlying data is mutated we're not using stale cursors and potentially getting duplicates or skipping records. If an infinite query's results are ever removed from the cache, the pagination restarts at the initial state with only the initial group being requested.

What if I need to pass custom information to my query function?

By default, the info returned from getFetchMore will be supplied to the query function, but in some cases, you may want to override this. You can pass custom variables to the fetchMore function which will override the default info like so:

1 function Projects() {
2   const fetchProjects = (key, cursor = 0) =>
3     fetch('/api/projects?cursor=' + cursor)
4 
5   const {
6     status,
7     data,
8     isFetching,
9     isFetchingMore,
10     fetchMore,
11     canFetchMore,
12   } = useInfiniteQuery('projects', fetchProjects, {
13     getFetchMore: (lastGroup, allGroups) => lastGroup.nextCursor,
14   })
15 
16   // Pass your own custom fetchMoreInfo
17   const skipToCursor50 = () => fetchMore(50)
18 }

What if I want to infinitely load more data in reverse?

Sometimes you may not want to append infinitely loaded data, but instead prepend it. If this is case, you can use fetchMore's previous option, eg.

 fetchMore(previousPageVariables, { previous: true })

This will ensure the new data is prepended to the data array instead of appended.