Paginated Queries

Rendering paginated data is a very common UI pattern to avoid overloading bandwidth or even your UI. React Query exposes a usePaginatedQuery that is very similar to useQuery that helps with this very scenario.

Consider the following example where we would ideally want to increment a pageIndex (or cursor) for a query. If we were to use useQuery, it would technically work fine, but the UI would jump in and out of the success and loading states as different queries are created and destroyed for each page or cursor. By using usePaginatedQuery we get a few new things:

• Instead of data, you should use resolvedData instead. This is the data from the last known successful query result. As new page queries resolve, resolvedData remains available to show the last page's data while a new page is requested. When the new page data is received, resolvedData gets updated to the new page's data.
• If you specifically need the data for the exact page being requested, latestData is available. When the desired page is being requested, latestData will be undefined until the query resolves, then it will get updated with the latest pages data result.

1 function Todos() {
2   const [page, setPage] = React.useState(0)
3 
4   const fetchProjects = (key, page = 0) => fetch('/api/projects?page=' + page)
5 
6   const {
7     isLoading,
8     isError,
9     error,
10     resolvedData,
11     latestData,
12     isFetching,
13   } = usePaginatedQuery(['projects', page], fetchProjects)
14 
15   return (
16     <div>
17       {isLoading ? (
18         <div>Loading...</div>
19       ) : isError ? (
20         <div>Error: {error.message}</div>
21       ) : (
22         // `resolvedData` will either resolve to the latest page's data
23         // or if fetching a new page, the last successful page's data
24         <div>
25           {resolvedData.projects.map(project => (
26             <p key={project.id}>{project.name}</p>
27           ))}
28         </div>
29       )}
30       <span>Current Page: {page + 1}</span>
31       <button
32         onClick={() => setPage(old => Math.max(old - 1, 0))}
33         disabled={page === 0}
34       >
35         Previous Page
36       </button>{' '}
37       <button
38         onClick={() =>
39           // Here, we use `latestData` so the Next Page
40           // button isn't relying on potentially old data
41           setPage(old => (!latestData || !latestData.hasMore ? old : old + 1))
42         }
43         disabled={!latestData || !latestData.hasMore}
44       >
45         Next Page
46       </button>
47       {
48         // Since the last page's data potentially sticks around between page requests,
49         // we can use `isFetching` to show a background loading
50         // indicator since our `status === 'loading'` state won't be triggered
51         isFetching ? <span> Loading...</span> : null
52       }{' '}
53     </div>
54   )
55 }