Master Pagination With UseInfiniteQuery For Smooth Data Loads

Have you been struggling with managing large datasets in your React applications?

The challenge of loading just the right amount of data while maintaining a smooth user experience is a common one.

This blog will guide you through mastering pagination with useInfiniteQuery, helping you implement infinite scroll functionality that loads data exactly when needed.

React Query and Infinite Scrolling

React Query has become a popular library for managing server state in React applications. One of its most powerful features is the useInfiniteQuery hook, which simplifies the implementation of infinite scrolling patterns.

Infinite scroll is a UI pattern where new content loads automatically as the user scrolls down a page. This creates a seamless browsing experience without requiring the user to click on pagination controls. When implemented correctly, infinite scroll makes the browsing experience feel natural and uninterrupted.

Why Traditional Pagination Falls Short

Traditional pagination requires users to click through numbered pages or "next" buttons to view more data. This interrupts the user experience and adds friction. In contrast, infinite scroll loads new data automatically as the user scrolls to the bottom of the current content, creating a smoother experience.

How useInfiniteQuery Hook Works

The useInfiniteQuery hook from React Query manages the complex state required for infinite scrolling. It keeps track of:

• The pages of data already loaded

• The current page being viewed

• Whether more data is available

• Loading states for initial and subsequent data requests

Unlike the standard useQuery hook, useInfiniteQuery structures data into pages, making it ideal for paginated data.

Setting Up Your Project with React Query

Before implementing infinite scroll, you need to set up React Query in your project:

1import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
2import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
3import App from './App'
4
5// Create a client
6const queryClient = new QueryClient()
7
8function Root() {
9  return (
10    <QueryClientProvider client={queryClient}>
11      <App />
12      <ReactQueryDevtools initialIsOpen={false} />
13    </QueryClientProvider>
14  )
15}

​

This code initializes a new QueryClient and wraps your application with the QueryClientProvider. The ReactQueryDevtools component adds a helpful debug panel for development.

Implementing useInfiniteQuery for Pagination

Now, let's look at how to implement infinite scrolling with useInfiniteQuery:

1import { useInfiniteQuery } from '@tanstack/react-query'
2import { useEffect } from 'react'
3import { useInView } from 'react-intersection-observer'
4
5function PostList() {
6  // Setup intersection observer to detect when user scrolls to bottom
7  const { ref, inView } = useInView()
8
9  // Setup infinite query
10  const {
11    data,
12    error,
13    fetchNextPage,
14    hasNextPage,
15    isFetching,
16    isFetchingNextPage,
17    status,
18  } = useInfiniteQuery({
19    queryKey: ['posts'],
20    queryFn: async ({ pageParam = 1 }) => {
21      const response = await fetch(
22        `https://api.example.com/posts?page=${pageParam}&limit=10`
23      )
24      if (!response.ok) {
25        throw new Error('Network response was not ok')
26      }
27      return response.json()
28    },
29    getNextPageParam: (lastPage, pages) => {
30      // Return undefined to indicate there are no more pages
31      return lastPage.nextPage || undefined
32    },
33  })
34
35  // Automatically fetch next page when user scrolls to bottom
36  useEffect(() => {
37    if (inView && hasNextPage && !isFetchingNextPage) {
38      fetchNextPage()
39    }
40  }, [inView, hasNextPage, isFetchingNextPage, fetchNextPage])
41
42  // Handle loading and error states
43  if (status === 'loading') return <div>Loading...</div>
44  if (status === 'error') return <div>Error: {error.message}</div>
45
46  return (
47    <div>
48      {data.pages.map((page, i) => (
49        <div key={i}>
50          {page.items.map(post => (
51            <div key={post.id} className="post-item">
52              <h3>{post.title}</h3>
53              <p>{post.excerpt}</p>
54            </div>
55          ))}
56        </div>
57      ))}
58
59      {/* Loading indicator at the bottom */}
60      <div ref={ref}>
61        {isFetchingNextPage
62          ? 'Loading more...'
63          : hasNextPage
64          ? 'Scroll to load more'
65          : 'No more data to load'}
66      </div>
67    </div>
68  )
69}

​

This component uses useInfiniteQuery to fetch posts from an API endpoint and display them. When the user scrolls to the bottom (detected by react-intersection-observer), it automatically loads the next page of data.

Understanding the Key Parameters of useInfiniteQuery

The useInfiniteQuery hook takes several important parameters:

queryKey

This parameter uniquely identifies your query for caching:

1queryKey: ['posts', filters, sortOrder]

​

If your filters or sorting options change, React Query will automatically refetch the data.

queryFn

The query function is responsible for fetching a single page of data. It receives a context object containing the pageParam:

1queryFn: async ({ pageParam = 1 }) => {
2  const response = await fetch(
3    `https://api.example.com/posts?page=${pageParam}&limit=10`
4  )
5  return response.json()
6}

​

The default value for pageParam (in this case, 1) is used for the first page.

getNextPageParam

This function determines the parameter for the next page request. It receives the last page data and all the pages array:

1getNextPageParam: (lastPage, pages) => {
2  // If the API doesn't indicate a next page, return undefined
3  if (!lastPage.hasMore) return undefined
4
5  // Otherwise, return the next page number
6  return lastPage.nextPage
7}

​

Returning undefined signals to React Query that there's no more data to load, effectively marking this as the last page.

Working with the Data Structure

The data returned by useInfiniteQuery has a specific structure that's different from regular queries:

1{
2  pages: [
3    { items: [...], nextPage: 2 },
4    { items: [...], nextPage: 3 },
5    { items: [...], nextPage: undefined }
6  ],
7  pageParams: [1, 2, 3]
8}

​

To display all the items, you need to map through pages and then map through each page's items:

1{data.pages.map((page, i) => (
2  <React.Fragment key={i}>
3    {page.items.map(item => (
4      <Item key={item.id} item={item} />
5    ))}
6  </React.Fragment>
7))}

​

Advanced Techniques for Infinite Scrolling

1. Bi-directional Infinite Scrolling

You can implement scrolling in both directions by using getPreviousPageParam and fetchPreviousPage:

1const {
2  data,
3  fetchNextPage,
4  fetchPreviousPage,
5  isFetchingPreviousPage,
6} = useInfiniteQuery({
7  queryKey: ['posts'],
8  queryFn: fetchPosts,
9  getNextPageParam: (lastPage) => lastPage.nextCursor,
10  getPreviousPageParam: (firstPage) => firstPage.prevCursor,
11  initialPageParam: 0,
12})

​

This approach is useful for chat applications or timelines where users may want to scroll up to see previous messages.

2. Implementing a Load More Button

If you prefer a button instead of automatic loading:

1<button
2  onClick={() => fetchNextPage()}
3  disabled={!hasNextPage || isFetchingNextPage}
4>
5  {isFetchingNextPage
6    ? 'Loading more...'
7    : hasNextPage
8    ? 'Load More'
9    : 'No more data'}
10</button>

​

3. Handling Initial Page Load Performance

For better performance, you might want to limit the initial data load:

1useInfiniteQuery({
2  queryKey: ['posts'],
3  queryFn: async ({ pageParam = 1 }) => {
4    const limit = pageParam === 1 ? 20 : 10
5    const response = await fetch(
6      `https://api.example.com/posts?page=${pageParam}&limit=${limit}`
7    )
8    return response.json()
9  },
10  // Other options...
11})

​

This code fetches more items on the first page to provide a better initial user experience.

Common Challenges and Solutions

Challenge 1: Maintaining Scroll Position

When new data is loaded, the browser might scroll unexpectedly. To prevent this:

1const scrollContainer = useRef(null)
2const [scrollPosition, setScrollPosition] = useState(0)
3
4// Save scroll position before fetching
5const handleFetchMore = async () => {
6  setScrollPosition(scrollContainer.current.scrollTop)
7  await fetchNextPage()
8}
9
10// Restore scroll position after data loads
11useEffect(() => {
12  if (!isFetchingNextPage && scrollContainer.current) {
13    scrollContainer.current.scrollTop = scrollPosition
14  }
15}, [isFetchingNextPage, data.pages.length])

​

Challenge 2: Handling Data Updates

If data items can be updated while displayed in an infinite list:

1const queryClient = useQueryClient()
2
3// After updating an item
4await queryClient.setQueryData(['posts'], (oldData) => {
5  return {
6    pages: oldData.pages.map(page => ({
7      ...page,
8      items: page.items.map(item =>
9        item.id === updatedItem.id ? updatedItem : item
10      )
11    })),
12    pageParams: oldData.pageParams
13  }
14})

​

Challenge 3: Error Handling and Retries

Implement robust error handling for a better user experience:

1const {
2  error,
3  fetchNextPage,
4  isError,
5} = useInfiniteQuery({
6  queryKey: ['posts'],
7  queryFn: fetchPosts,
8  retry: 3,
9  retryDelay: attempt => Math.min(1000 * 2 ** attempt, 30000),
10  onError: (error) => {
11    console.error('Failed to fetch posts:', error)
12  }
13})
14
15// In your component
16if (isError) {
17  return (
18    <div className="error-container">
19      <p>Failed to load data: {error.message}</p>
20      <button onClick={() => fetchNextPage()}>Try Again</button>
21    </div>
22  )
23}

​

Optimizing Performance

1. Using the select Option

The select option allows you to transform your data before it's stored in the cache:

1useInfiniteQuery({
2  queryKey: ['posts'],
3  queryFn: fetchPosts,
4  select: data => ({
5    pages: data.pages.map(page => ({
6      ...page,
7      items: page.items.map(item => ({
8        id: item.id,
9        title: item.title,
10        // Only select needed fields to reduce memory usage
11      }))
12    })),
13    pageParams: data.pageParams
14  })
15})

​

2. Implementing Virtualization

For very long lists, consider using virtualization to render only visible items:

1import { useVirtualizer } from '@tanstack/react-virtual'
2
3function VirtualizedPostList() {
4  // Your infinite query setup here...
5
6  // Flatten all items from all pages
7  const allItems = data ? data.pages.flatMap(page => page.items) : []
8
9  const parentRef = useRef()
10
11  const virtualizer = useVirtualizer({
12    count: allItems.length,
13    getScrollElement: () => parentRef.current,
14    estimateSize: () => 100,
15  })
16
17  return (
18    <div
19      ref={parentRef}
20      style={{ height: '800px', overflow: 'auto' }}
21    >
22      <div
23        style={{
24          height: `${virtualizer.getTotalSize()}px`,
25          position: 'relative',
26        }}
27      >
28        {virtualizer.getVirtualItems().map(virtualRow => (
29          <div
30            key={virtualRow.index}
31            style={{
32              position: 'absolute',
33              top: 0,
34              left: 0,
35              width: '100%',
36              height: `${virtualRow.size}px`,
37              transform: `translateY(${virtualRow.start}px)`,
38            }}
39          >
40            <PostItem item={allItems[virtualRow.index]} />
41          </div>
42        ))}
43      </div>
44
45      {/* Load more trigger */}
46      <div ref={ref}></div>
47    </div>
48  )
49}

​

Real-world Examples

Example 1: News Feed

1function NewsFeed() {
2  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
3    queryKey: ['feed'],
4    queryFn: async ({ pageParam = null }) => {
5      const url = pageParam
6        ? `https://api.news.com/feed?cursor=${pageParam}`
7        : 'https://api.news.com/feed'
8
9      const response = await fetch(url)
10      return response.json()
11    },
12    getNextPageParam: (lastPage) => lastPage.nextCursor || undefined,
13  })
14
15  // Implementation details...
16}

​

Example 2: Product Search with Filters

1function ProductSearch({ category, priceRange, sortBy }) {
2  const { data, fetchNextPage } = useInfiniteQuery({
3    queryKey: ['products', category, priceRange, sortBy],
4    queryFn: async ({ pageParam = 1 }) => {
5      const params = new URLSearchParams({
6        page: pageParam,
7        category,
8        minPrice: priceRange[0],
9        maxPrice: priceRange[1],
10        sortBy
11      })
12
13      const response = await fetch(`https://api.store.com/products?${params}`)
14      return response.json()
15    },
16    getNextPageParam: (lastPage, pages) =>
17      lastPage.products.length === 0 ? undefined : pages.length + 1,
18  })
19
20  // Implementation details...
21}

​

Testing Your Infinite Query Implementation

Writing tests for infinite query implementations ensures they work correctly:

1import { renderHook, act } from '@testing-library/react-hooks'
2import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
3import { useInfiniteProductList } from './hooks'
4
5test('fetches next page when fetchNextPage is called', async () => {
6  const queryClient = new QueryClient()
7  const wrapper = ({ children }) => (
8    <QueryClientProvider client={queryClient}>
9      {children}
10    </QueryClientProvider>
11  )
12
13  const { result, waitFor } = renderHook(() => useInfiniteProductList(), { wrapper })
14
15  // Wait for initial query to complete
16  await waitFor(() => result.current.status === 'success')
17
18  // Fetch next page
19  act(() => {
20    result.current.fetchNextPage()
21  })
22
23  // Wait for next page to load
24  await waitFor(() => result.current.isFetchingNextPage === false)
25
26  // Verify we have more than one page
27  expect(result.current.data.pages.length).toBeGreaterThan(1)
28})

​

The Bottom Line!

Implementing infinite scrolling with useInfiniteQuery makes handling large datasets in React applications much more manageable. This approach not only improves user experience but also optimizes performance by loading data only when needed.

The useInfiniteQuery hook provides a powerful and flexible solution for pagination challenges. By understanding its core concepts and applying the techniques outlined in this post, you can create smooth, responsive interfaces that handle large data sets with ease.

Remember that successful implementation depends on:

1. Structuring your API endpoint to support pagination parameters

2. Correctly managing the pages array of data

3. Implementing proper loading indicators

4. Handling error states appropriately

With these foundations in place, you can build applications that load and display data seamlessly as the user needs it.

Short on time? Speed things up with DhiWise!

Tired of manually designing screens, coding on weekends, and technical debt? Let DhiWise handle it for you!

You can build an e-commerce store, healthcare app, portfolio, blogging website, social media or admin panel right away. Use our library of 40+ pre-built free templates to create your first application using DhiWise.