Infinite Scroll with TanStack Query: Best Practices

Infinite Scroll Done Right with TanStack Query

Infinite scroll, that smooth, endless feed experience, is everywhere. Think social media feeds, product listings, you name it. It feels great for users, but implementing it well can be tricky. We want to avoid performance headaches and keep things responsive. Thankfully, TanStack Query (formerly React Query) makes this a whole lot simpler.

Let’s break down how to implement infinite scroll effectively using TanStack Query’s useInfiniteQuery hook. We’re aiming for a robust solution that handles loading states, errors, and fetching more data seamlessly.

The Core: useInfiniteQuery

The useInfiniteQuery hook is TanStack Query’s answer to paginated or infinite data. It’s designed to fetch data in chunks, manage the state of these chunks, and provide methods to fetch subsequent ones.

At its heart, useInfiniteQuery takes a query key and a query function. The query function receives an InfiniteData object which contains information about the current page. Crucially, it also has a pageParam property. This pageParam is what allows us to tell the API what data to fetch next.

Here’s a basic setup:

1
import { useInfiniteQuery } from '@tanstack/react-query';
2
import axios from 'axios';
3

4
const fetchPosts = async ({ pageParam = 1 }) => {
5
  const { data } = await axios.get(`/api/posts?page=${pageParam}&limit=10`);
6
  return data;
7
};
8

9
function PostList() {
10
  const {
11
    data,
12
    error,
13
    fetchNextPage,
14
    hasNextPage,
15
    isFetchingNextPage
16
  } = useInfiniteQuery({
17
    queryKey: ['posts'],
18
    queryFn: fetchPosts,
19
    initialPageParam: 1,
20
    getNextPageParam: (lastPage, allPages) => {
21
      // Assuming your API returns a 'nextPage' property or similar
22
      // If there's no next page, return undefined
23
      if (!lastPage.nextPage) {
24
        return undefined;
25
      }
26
      return lastPage.nextPage;
27
    },
28
  });
29

30
  if (error) return 'An error has occurred: ' + error.message;
31

32
  return (
33
    <div>
34
      {data.pages.map((page, i) => (
35
        <React.Fragment key={i}>
36
          {page.posts.map(post => (
37
            <div key={post.id}>{post.title}</div>
38
          ))}
39
        </React.Fragment>
40
      ))}
41
      <button
42
        onClick={() => fetchNextPage()}
43
        disabled={!hasNextPage || isFetchingNextPage}
44
      >
45
        {isFetchingNextPage
46
          ? 'Loading more...'
47
          : hasNextPage
48
          ? 'Load More'
49
          : 'Nothing more to load'}
50
      </button>
51
    </div>
52
  );
53
}

Understanding the Key Parts

1. queryKey: A unique identifier for this query. TanStack Query uses this for caching and refetching.
2. queryFn: Your actual data-fetching function. It receives an object with pageParam. Your function needs to use this pageParam to fetch the correct slice of data.
3. initialPageParam: The starting point for your pageParam. Usually 1 for page-based pagination or an offset like 0.
4. getNextPageParam: This is crucial. TanStack Query calls this function after a successful fetch. It receives the lastPage (the most recently fetched data) and allPages (an array of all fetched pages). Your job is to return the pageParam for the next fetch. If there’s no next page, return undefined. This tells useInfiniteQuery to stop fetching.

Enhancing the User Experience

The example above uses a button to trigger fetchNextPage. For true infinite scroll, we want this to happen automatically as the user scrolls.

We can achieve this by using the Intersection Observer API. We’ll attach a ref to a “sentinel” element – an element that sits at the bottom of our currently loaded content. When this sentinel enters the viewport, we trigger fetchNextPage.

1
import { useInfiniteQuery } from '@tanstack/react-query';
2
import axios from 'axios';
3
import React, { useEffect, useRef } from 'react';
4

5
const fetchPosts = async ({ pageParam = 1 }) => {
6
  const { data } = await axios.get(`/api/posts?page=${pageParam}&limit=10`);
7
  return data;
8
};
9

10
function PostListInfinite() {
11
  const {
12
    data,
13
    error,
14
    fetchNextPage,
15
    hasNextPage,
16
    isFetchingNextPage
17
  } = useInfiniteQuery({
18
    queryKey: ['posts'],
19
    queryFn: fetchPosts,
20
    initialPageParam: 1,
21
    getNextPageParam: (lastPage, allPages) => {
22
      if (!lastPage.nextPage) {
23
        return undefined;
24
      }
25
      return lastPage.nextPage;
26
    },
27
  });
28

29
  const observer = useRef();
30
  const lastPostRef = React.useCallback(node => {
31
    if (isFetchingNextPage) return;
32
    if (observer.current) observer.current.disconnect();
33
    observer.current = new IntersectionObserver(entries => {
34
      if (entries[0].isIntersecting && hasNextPage) {
35
        fetchNextPage();
36
      }
37
    });
38
    if (node) observer.current.observe(node);
39
  }, [isFetchingNextPage, hasNextPage, fetchNextPage]);
40

41
  if (error) return 'An error has occurred: ' + error.message;
42

43
  return (
44
    <div>
45
      {data.pages.map((page, i) => (
46
        <React.Fragment key={i}>
47
          {page.posts.map((post, postIndex) => (
48
            <div
49
              key={post.id}
50
              ref={page.posts.length === postIndex + 1 && page.posts.length * (i + 1) === data.pages.reduce((sum, p) => sum + p.posts.length, 0) ? lastPostRef : null} // Attach ref to the last item of the last page
51
            >
52
              {post.title}
53
            </div>
54
          ))}
55
        </React.Fragment>
56
      ))}
57
      {isFetchingNextPage && <div>Loading more posts...</div>}
58
    </div>
59
  );
60
}

In this enhanced version:

• We use useRef to create a ref for our sentinel element.
• lastPostRef is a callback ref that gets attached to the last item of the last fetched page. This element acts as our trigger.
• An IntersectionObserver is set up. When the lastPostRef element enters the viewport (isIntersecting), and if there’s a hasNextPage, we call fetchNextPage().
• We conditionally render a “Loading more posts…” message when isFetchingNextPage is true, providing visual feedback.

Key Considerations

• Error Handling: Always provide clear error messages to the user. TanStack Query makes error readily available.
• Loading States: Differentiate between the initial loading state and subsequent page fetches (isFetchingNextPage). Show spinners or skeleton loaders accordingly.
• API Design: Your backend API should support efficient pagination. Cursor-based pagination is often superior to offset/page-based for true infinite scrolling, as it avoids issues with data shifting.
• Performance: TanStack Query handles caching and deduplication automatically, which is a massive performance win. However, be mindful of how much data you’re rendering on the client-side at once.

Implementing infinite scroll doesn’t have to be a chore. With useInfiniteQuery and a touch of Intersection Observer magic, you can build smooth, performant infinite scrolling experiences that users will love. It’s a powerful pattern when done right.