Infinite Queries

· abundance's blog

Rendering lists that can additively "load more" data onto an existing set of data or "infinite scroll" is also a very common UI pattern. TanStack 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:

Note: Options initialData or placeholderData need to conform to the same structure of an object with data.pages and data.pageParams properties.

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:

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

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

 1import { useInfiniteQuery } from '@tanstack/react-query'
 2
 3function Projects() {
 4  const fetchProjects = async ({ pageParam }) => {
 5    const res = await fetch('/api/projects?cursor=' + pageParam)
 6    return res.json()
 7  }
 8
 9  const {
10    data,
11    error,
12    fetchNextPage,
13    hasNextPage,
14    isFetching,
15    isFetchingNextPage,
16    status,
17  } = useInfiniteQuery({
18    queryKey: ['projects'],
19    queryFn: fetchProjects,
20    initialPageParam: 0,
21    getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
22  })
23
24  return status === 'pending' ? (
25    <p>Loading...</p>
26  ) : status === 'error' ? (
27    <p>Error: {error.message}</p>
28  ) : (
29    <>
30      {data.pages.map((group, i) => (
31        <React.Fragment key={i}>
32          {group.data.map((project) => (
33            <p key={project.id}>{project.name}</p>
34          ))}
35        </React.Fragment>
36      ))}
37      <div>
38        <button
39          onClick={() => fetchNextPage()}
40          disabled={!hasNextPage || isFetchingNextPage}
41        >
42          {isFetchingNextPage
43            ? 'Loading more...'
44            : hasNextPage
45              ? 'Load More'
46              : 'Nothing more to load'}
47        </button>
48      </div>
49      <div>{isFetching && !isFetchingNextPage ? 'Fetching...' : null}</div>
50    </>
51  )
52}

It's essential to understand that calling fetchNextPage while an ongoing fetch is in progress runs the risk of overwriting data refreshes happening in the background. This situation becomes particularly critical when rendering a list and triggering fetchNextPage simultaneously.

Remember, there can only be a single ongoing fetch for an InfiniteQuery. A single cache entry is shared for all pages, attempting to fetch twice simultaneously might lead to data overwrites.

If you intend to enable simultaneous fetching, you can utilize the { cancelRefetch: false } option (default: true) within fetchNextPage.

To ensure a seamless querying process without conflicts, it's highly recommended to verify that the query is not in an isFetching state, especially if the user won't directly control that call.

1<List onEndReached={() => !isFetching && fetchNextPage()} />

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 queryCache, the pagination restarts at the initial state with only the initial group being requested.

What if I want to implement a bi-directional infinite list? #

Bi-directional lists can be implemented by using the getPreviousPageParam, fetchPreviousPage, hasPreviousPage and isFetchingPreviousPage properties and functions.

1useInfiniteQuery({
2  queryKey: ['projects'],
3  queryFn: fetchProjects,
4  initialPageParam: 0,
5  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
6  getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,
7})

What if I want to show the pages in reversed order? #

Sometimes you may want to show the pages in reversed order. If this is case, you can use the select option:

1useInfiniteQuery({
2  queryKey: ['projects'],
3  queryFn: fetchProjects,
4  select: (data) => ({
5    pages: [...data.pages].reverse(),
6    pageParams: [...data.pageParams].reverse(),
7  }),
8})

What if I want to manually update the infinite query? #

Manually removing first page: #

1queryClient.setQueryData(['projects'], (data) => ({
2  pages: data.pages.slice(1),
3  pageParams: data.pageParams.slice(1),
4}))

Manually removing a single value from an individual page: #

1const newPagesArray =
2  oldPagesArray?.pages.map((page) =>
3    page.filter((val) => val.id !== updatedId),
4  ) ?? []
5
6queryClient.setQueryData(['projects'], (data) => ({
7  pages: newPagesArray,
8  pageParams: data.pageParams,
9}))

Keep only the first page: #

1queryClient.setQueryData(['projects'], (data) => ({
2  pages: data.pages.slice(0, 1),
3  pageParams: data.pageParams.slice(0, 1),
4}))

Make sure to always keep the same data structure of pages and pageParams!

What if I want to limit the number of pages? #

In some use cases you may want to limit the number of pages stored in the query data to improve the performance and UX:

The solution is to use a "Limited Infinite Query". This is made possible by using the maxPages option in conjunction with getNextPageParam and getPreviousPageParam to allow fetching pages when needed in both directions.

In the following example only 3 pages are kept in the query data pages array. If a refetch is needed, only 3 pages will be refetched sequentially.

1useInfiniteQuery({
2  queryKey: ['projects'],
3  queryFn: fetchProjects,
4  initialPageParam: 0,
5  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
6  getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,
7  maxPages: 3,
8})

What if my API doesn't return a cursor? #

If your API doesn't return a cursor, you can use the pageParam as a cursor. Because getNextPageParam and getPreviousPageParam also get the pageParamof the current page, you can use it to calculate the next / previous page param.

 1return useInfiniteQuery({
 2  queryKey: ['projects'],
 3  queryFn: fetchProjects,
 4  initialPageParam: 0,
 5  getNextPageParam: (lastPage, allPages, lastPageParam) => {
 6    if (lastPage.length === 0) {
 7      return undefined
 8    }
 9    return lastPageParam + 1
10  },
11  getPreviousPageParam: (firstPage, allPages, firstPageParam) => {
12    if (firstPageParam <= 1) {
13      return undefined
14    }
15    return firstPageParam - 1
16  },
17})