8. Пагинация и Infinite Query

В TanStack Query есть два основных сценария:

1. offset/page pagination через обычный useQuery
2. cursor/infinite pagination через useInfiniteQuery

Offset pagination

const projectsQuery = useQuery({
  queryKey: ['projects', { page, pageSize, status }],
  queryFn: () => fetchProjects({ page, pageSize, status }),
  placeholderData: (previousData) => previousData,
})

Это современный v5-паттерн для плавного перехода между страницами. Исторический helper keepPreviousData больше не является центральной рекомендацией; основной способ сегодня это placeholderData: (prev) => prev.

Что даёт placeholderData

• предыдущая страница остаётся на экране
• новый запрос стартует в фоне
• пользователь не видит пустой экран
• isPlaceholderData помогает понять, что сейчас показаны временные данные

if (query.isPlaceholderData) {
  // например, можно временно блокировать кнопку Next
}

Включайте параметры страницы в queryKey

Правильно:

['projects', { page, pageSize, status }]

Неправильно:

• держать page только в локальном state
• не включать фильтры в ключ

Иначе страницы будут смешиваться в кеше.

Предзагрузка соседней страницы

useEffect(() => {
  if (!query.data?.hasMore) return

  void queryClient.prefetchQuery({
    queryKey: ['projects', { page: page + 1, pageSize, status }],
    queryFn: () => fetchProjects({ page: page + 1, pageSize, status }),
    staleTime: 30_000,
  })
}, [page, pageSize, status, query.data?.hasMore, queryClient])

Это уменьшает perceived latency при клике “Next”.

Infinite Query

import { useInfiniteQuery } from '@tanstack/react-query'

const messagesQuery = useInfiniteQuery({
  queryKey: ['messages', roomId],
  initialPageParam: null as string | null,
  queryFn: ({ pageParam, signal }) =>
    fetchMessages({ roomId, cursor: pageParam, signal }),
  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
})

Ключевые поля:

• data.pages
• data.pageParams
• fetchNextPage
• hasNextPage
• isFetchingNextPage

Рендер infinite list

return (
  <>
    {messagesQuery.data.pages.flatMap((page) =>
      page.items.map((message) => (
        <MessageRow key={message.id} message={message} />
      )),
    )}

    <button
      onClick={() => messagesQuery.fetchNextPage()}
      disabled={!messagesQuery.hasNextPage || messagesQuery.isFetchingNextPage}
    >
      {messagesQuery.isFetchingNextPage ? 'Loading...' : 'Load more'}
    </button>
  </>
)

maxPages

Если лента очень длинная, не держите весь стек страниц бесконечно:

useInfiniteQuery({
  queryKey: ['feed'],
  initialPageParam: null,
  queryFn: ({ pageParam }) => fetchFeed(pageParam),
  getNextPageParam: (lastPage) => lastPage.nextCursor,
  maxPages: 10,
})

Это полезно для чатов, activity feed и мобильных интерфейсов.

usePrefetchInfiniteQuery

Для Suspense и предварительной загрузки во время render-подготовки:

usePrefetchInfiniteQuery({
  queryKey: ['feed'],
  initialPageParam: null,
  queryFn: ({ pageParam }) => fetchFeed(pageParam),
  getNextPageParam: (lastPage) => lastPage.nextCursor,
})

Этот hook ничего не возвращает. Его задача только прогреть кеш до useSuspenseInfiniteQuery.

SSR и hydration для infinite query

Правило:

• на сервере и на клиенте должны совпадать queryKey, initialPageParam и логика getNextPageParam

Иначе гидратация будет непредсказуемой, а первая страница может запроситься повторно.

Обновление infinite cache после мутации

queryClient.setQueryData(['messages', roomId], (old: InfiniteData<MessagesPage>) =>
  old
    ? {
        ...old,
        pages: old.pages.map((page, index) =>
          index === 0
            ? { ...page, items: [newMessage, ...page.items] }
            : page,
        ),
      }
    : old,
)

Для insert/delete в середине списка часто проще и безопаснее инвалидировать, чем пытаться идеально патчить все страницы.

Infinite scroll и IntersectionObserver

Обычный паттерн:

• у вас есть sentinel-элемент внизу списка
• при входе в viewport вызывается fetchNextPage()

При больших списках почти всегда стоит комбинировать это с виртуализацией вроде @tanstack/react-virtual.

Типичные ошибки

• не включить фильтры и sort в ключ
• забыть initialPageParam
• держать в infinite query offset-пагинацию, когда API на самом деле cursor-based
• пытаться хранить бесконечный стек страниц без maxPages