Tanstack Infinite Queries

# 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.

```typescript
// 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.