TanStack Query: Infinite Queries

Implement cursor-based pagination and "load more" UX with useInfiniteQuery

When to Use

• Building infinite scroll feeds (social media, activity logs, search results)
• Implementing "Load More" button pagination without traditional page numbers
• Fetching cursor-based APIs that return a

  nextCursor

  or

  nextPageToken

• Building virtualized lists that load additional data as the user scrolls

Instructions

1. Use

   useInfiniteQuery

   instead of

   useQuery

   for paginated data that loads incrementally.
2. Provide

   initialPageParam

   (the starting cursor or page number) and

   getNextPageParam

   (extracts the next cursor from the last page's response).
3. Access all loaded pages via

   data.pages

   — an array of page responses. Flatten with

   flatMap

   to produce a single item list.
4. Access

   data.pageParams

   to get the list of params used for each loaded page.
5. Call

   fetchNextPage()

   to load the next page — trigger this on scroll, button click, or intersection observer.
6. Check

   hasNextPage

   before showing a "load more" button — it returns

   false

   when

   getNextPageParam

   returns

   undefined

   .
7. Use

   isFetchingNextPage

   to show a loading indicator during incremental loads without hiding existing data.
8. Pair with

   IntersectionObserver

   or

   react-intersection-observer

   for true infinite scroll.

// queries/posts.ts — infinite query setup
import { useInfiniteQuery } from '@tanstack/react-query';

interface PostsPage {
  posts: Post[];
  nextCursor: string | null;
}

export function useInfinitePosts(filters: PostFilters) {
  return useInfiniteQuery({
    queryKey: ['posts', 'infinite', filters],
    queryFn: ({ pageParam }) =>
      fetch(`/api/posts?cursor=${pageParam}&limit=20&${new URLSearchParams(filters)}`)
        .then<PostsPage>(r => r.json()),
    initialPageParam: '',
    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
    // undefined signals no more pages → hasNextPage = false
  });
}

// components/post-feed.tsx — infinite scroll with intersection observer
import { useRef, useEffect } from 'react';
import { useInfinitePosts } from '@/queries/posts';

export function PostFeed({ filters }: { filters: PostFilters }) {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfinitePosts(filters);
  const sentinelRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const observer = new IntersectionObserver(entries => {
      if (entries[0].isIntersecting && hasNextPage && !isFetchingNextPage) {
        fetchNextPage();
      }
    });
    if (sentinelRef.current) observer.observe(sentinelRef.current);
    return () => observer.disconnect();
  }, [fetchNextPage, hasNextPage, isFetchingNextPage]);

  const posts = data?.pages.flatMap(page => page.posts) ?? [];

  return (
    <div>
      {posts.map(post => <PostCard key={post.id} post={post} />)}
      <div ref={sentinelRef} />
      {isFetchingNextPage && <LoadingSpinner />}
    </div>
  );
}

Details

useInfiniteQuery

stores each page response in

data.pages

as a separate array element. This structure allows TanStack Query to append new pages without mutating existing ones, enabling React to optimize re-renders — only the new page's components re-render when a page loads.

getNextPageParam

contract: Return the next page's param value (cursor, page number, offset) to signal more pages exist. Return

undefined

(or

null

) to signal the end of data — TanStack Query sets

hasNextPage

to

false

.

Cursor vs offset pagination: Cursor-based pagination (returning an opaque

nextCursor

) is more reliable than offset (

page=2

) for feeds with real-time inserts. Offset pagination can miss items or show duplicates if new items are inserted at the top between page loads.

Flattening pages:

data.pages

is

PostsPage[][]

logically — an array of page objects each containing an

items

array. Use

data.pages.flatMap(page => page.posts)

to get a flat

Post[]

for rendering. Memoize this with

useMemo

if the list is large and re-renders are frequent.

Prefetching the next page: Call

queryClient.prefetchInfiniteQuery()

with

{ pages: 1 }

to warm the cache for the first page on hover. Prefetching subsequent pages is complex and usually not worth the complexity.

Refetch behavior:

refetchPage

controls which pages refetch on invalidation. By default, all pages refetch. Pass

refetchPage: (lastPage, index) => index === 0

to only refetch the first page — useful for feeds where older pages are effectively immutable.

Source

https://tanstack.com/query/latest/docs/framework/react/guides/infinite-queries

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.