How to take advantage of the useInfiniteQuery getPreviousPageParam function?

[Dev10000]

I'm not sure how to use the getPreviousPageParam function, and I'm curious about its specific use cases?

I couldn't find any examples online; it seems like everyone is only using getNextPageParam. Any guidance or some examples of how to use getPreviousPageParam, especially when implementing classic pagination or am I better of using useQuery for classic pagination?

Is the getPreviousPageParam mainly intended for use with APIs that support a previous cursor? I ask because I can also obtain the previous cursor from the fetched data data.pages array (see below). Are there any specific advantages to using getPreviousPageParam in such cases?

getPreviousPageParam: (firstPage, allPages) => {
          // If there is no previous page, we return undefined
          if (allPages.length <= 1) {
            return undefined;
          }
          // Otherwise, we return the cursor of the previous page
          return allPages?.[allPages.length - 2]?.nextCursor;
        },

Also implementing support for a previous cursor in an API would require an additional database operation to scan backwards (in descending order), which would slow down the query. Given the additional cost of the second operation, wouldn't an offset-based API be a better option in this case?

I'm trying to implement classic page pagination so that I can store the pagination state in the URL (page and page size or cursor). I'm wondering if it's possible to achieve this using a cursor-based API with useInfiniteQuery and getPreviousPageParam, or if I should use useQuery instead. I'm starting to feel that useInfiniteQuery and cursors may not be the right approach for classic pagination, especially if I want to store the state in the URL. Of course, if I make the API support a previous cursor, then I could store the state in the URL but data updates would cause additional trouble for the old cursor (the page number would not match with the old cursor).

Example - Current test implementation

Currently, I'm implementing the classic pagination using useInfiniteQuery and the fetchNextPage function. It works, but I'd like to improve its performance by, for example, prefetching some pages so that they don't need to be loaded with every page change. The back button is instant as the data is already loaded. You can test it here.

I am using tRPC T3 stack so the query syntax is little different.

To keep track of the current page that gets rendered, I use the page number to select the appropriate page from the data.pages array. If the user clicks the next page button, I check the length of data.pages array and if < new page number call fetchNextPage. If the user clicks the back button, I simply use the page number to select the previously fetched page, which is already included in the data.pages array.

const [test, setTest] = useState<number>(0);
const page = useRef<number>(0);

const { data, hasNextPage, fetchNextPage, isFetching } =
  api.journey.getAll.useInfiniteQuery(
    {
      limit: pageSize,
    },
    {
      getNextPageParam: (lastPage) => lastPage?.nextCursor,
    },
  );

// currentPage is the page that gets rendered
const currentPage = data?.pages[page.current]?.journeys

const handlePageChange = (newPage: number) => {
  const numberOfPages = data?.pages.length ?? 0;

  if (newPage > numberOfPages - 1) {
    page.current = newPage;
    return void fetchNextPage();
  }
  page.current = newPage;
  // setTest is only to activate rerender when going backwards as I am using useRef for the page
  setTest((prev) => prev + 1);

};

[TkDodo]

all of this is up to you. getPreviousPageParam is there so that you can have a query where you scroll to the top and add some data on that end as well. Our official example does that:

https://codesandbox.io/s/github/tanstack/query/tree/main/examples/react/load-more-infinite-scroll

[Dev10000]

Thanks for the reply, I really appreciate it. And sorry for missing those great examples. I tried searching for 'getPreviousPageParam' on Google, but it seems to have missed your examples. In other words, the API should support the previous cursor, and for classic page pagination, it's better to use 'useQuery'.

I'm now wondering about the official bi-directional infinite list example. Does it work with real-time data? For instance, if you scroll to the top or bottom of the list and new data is added later, in that case, it seems that the query is not able to find the previous or next cursor, as they would be undefined from the previous query. As a result, the 'hasNextPage' would be false, even if there is new data.

[TkDodo]

the API should support the previous cursor, and for classic page pagination, it's better to use 'useQuery'.

yep.

I'm now wondering about the official bi-directional infinite list example. Does it work with real-time data? For instance, if you scroll to the top or bottom of the list and new data is added later, in that case, it seems that the query is not able to find the previous or next cursor, as they would be undefined from the previous query. As a result, the 'hasNextPage' would be false, even if there is new data.

If you scroll to the bottom and there is no data, fetching is stopped. If data is added "later", it won't automatically appear. However, if you refetch the infinite query, e.g. because it is stale and you re-focus the window, or because you have set up interval fetching, all pages will be re-fetched in-order, so the last page will then know that there is a next page available.

[Makumiii]

For classical pagination just use useQuery