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

TanStack Query v5 предлагает два базовых подхода, но внутри каждого скрывается много тонкостей:

Страничная (offset-based) — useQuery на каждую страницу, управление page и кэшом.
Бесконечная (cursor-based) — useInfiniteQuery, курсоры и стек страниц/курсорных ответов.

Важно: в v5 gcTime по умолчанию 5 минут, поэтому при переключении страниц реже 5 минут данные не будут удаляться; при необходимости увеличьте gcTime или используйте meta.keepForever.

Offset пагинация с `keepPreviousData`

const pageSize = 20;

const { data, isFetching, isPlaceholderData } = useQuery({
  queryKey: ['projects', { page, pageSize }],
  queryFn: () => fetchProjects({ page, pageSize }),
  placeholderData: keepPreviousData,
});

placeholderData: keepPreviousData удерживает предыдущую страницу, пока новая загружается.
Храните page в URL (useSearchParams) и включайте в queryKey.
Не забывайте сбрасывать page на 1 при смене фильтров.
Если API возвращает total, сохраняйте его в select, чтобы не пересчитывать внутри компонента:
```
select: data => ({ items: data.items, totalPages: Math.ceil(data.total / pageSize) })
```
Для списков с множеством фильтров удобно формировать queryKey через массив: ['projects', { page, pageSize, ...filters }]. Это предотвращает кеш-коллизии.
Чтобы не загружать «пустых» страниц, используйте enabled: page > 0.

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

useEffect(() => {
  if (!data?.hasNextPage) return;
  queryClient.prefetchQuery({
    queryKey: ['projects', { page: page + 1, pageSize }],
    queryFn: () => fetchProjects({ page: page + 1, pageSize }),
    staleTime: 30_000,
  });
}, [data?.hasNextPage, page, pageSize, queryClient]);

keepPreviousData не блокирует isFetching, поэтому можно отображать спиннер поверх старых данных или индикатор skeleton внизу.
При suspense: true используйте placeholderData только если понимаете, что Suspense fallback не нужен.

Cursor пагинация через `useInfiniteQuery`

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

const messagesQuery = userId => ({
  queryKey: ['messages', userId],
  queryFn: ({ pageParam }) => fetchMessages({ userId, cursor: pageParam }),
  getNextPageParam: lastPage => lastPage.nextCursor ?? undefined,
  initialPageParam: null,
});

const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
  useInfiniteQuery(messagesQuery(currentUserId));

data.pages — массив результатов (каждая страница).
getNextPageParam получает последнюю страницу и возвращает курсор для следующей.
initialPageParam задаёт курсор для первой страницы.
Верните null/undefined из getNextPageParam, чтобы остановить подгрузку.
При необходимости прокрутки вверх реализуйте getPreviousPageParam.
pageParams хранит курсоры для каждой страницы — можно использовать их для refetchPage.

Ограничение размера стека

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

const { data } = useInfiniteQuery({
  ...messagesQuery(userId),
  maxPages: 20, // новые страницы вытесняют самые старые
});

Управление ошибками по страницам

refetchPage позволяет перезапрашивать только упавшую страницу:

const retryFailedPage = (pageIdx: number) =>
  queryClient.refetchQueries({
    queryKey: ['messages', userId],
    type: 'active',
    exact: true,
    meta: { refetchPage: (_, idx) => idx === pageIdx },
  });

Рендер списка страниц

return (
  <>
    {data?.pages.flatMap(page =>
      page.items.map(message => <Message key={message.id} {...message} />),
    )}
    <button onClick={() => fetchNextPage()} disabled={!hasNextPage || isFetchingNextPage}>
      {isFetchingNextPage ? 'Загружаем…' : hasNextPage ? 'Загрузить ещё' : 'Это всё'}
    </button>
  </>
);

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

const queryClient = useQueryClient();

const prefetchNext = () =>
  queryClient.prefetchInfiniteQuery({
    ...messagesQuery(userId),
    pages: data?.pages,
    pageParam: data?.pageParams,
  });

Вызывайте на onMouseEnter кнопки «Следующая страница».

Автоподгрузка по `IntersectionObserver`

const sentinelRef = useIntersectionObserver({
  onIntersect: () => hasNextPage && !isFetchingNextPage && fetchNextPage(),
  rootMargin: '400px',
});

return (
  <>
    {data?.pages.flatMap(...)}
    <div ref={sentinelRef}>{isFetchingNextPage && 'Загрузка...'}</div>
  </>
);

Для SSR избегайте IntersectionObserver до монтирования (проверяйте typeof window).
Можно использовать @tanstack/react-virtual и вызывать fetchNextPage при достижении последней виртуальной строки.

Сброс при фильтрации

const filters = useMemo(() => ({ status, sort }), [status, sort]);

const query = useInfiniteQuery({
  ...ticketsQuery(filters),
  enabled: !!projectId,
});

Меняйте queryKey, когда фильтры обновляются, чтобы кеш не смешивался.

Восстановление скролла

Сохраняйте scrollTop в useEffect и восстанавливайте при возврате на страницу, если queryClient уже содержит данные.
В react-router 6.16+ можно использовать useScrollRestoration, но важно вызывать его после того, как data.pages уже восстановились из кеша.

SSR + бесконечные запросы

На сервере используйте queryClient.prefetchInfiniteQuery.
Передавайте initialPageParam и pageParams в dehydrate.
На клиенте обязательно прокиньте initialPageParam в useInfiniteQuery, иначе первая страница запросится повторно.
При гидратации безопасно передавать только необходимый диапазон страниц, чтобы не раздувать HTML.

События и оптимизация

hasPreviousPage/fetchPreviousPage поддерживают прокрутку вверх (Slack-подобные UI).
Храните виртуализованный список (react-virtualized, tanstack-virtual) и обновляйте его при добавлении страниц.
Если API возвращает totalCount, можно вычислить «загружено из total» и построить индикатор прогресса.

Мутации и синхронизация списков

После создания/удаления сущности обновляйте последнюю страницу через queryClient.setQueryData:

const utils = useQueryClient();
const mutation = useMutation({
  mutationFn: createMessage,
  onSuccess: newMessage => {
    utils.setQueryData(['messages', userId], data => {
      if (!data) return data;
      return {
        ...data,
        pages: data.pages.map((page, idx) =>
          idx === 0 ? { ...page, items: [newMessage, ...page.items] } : page,
        ),
      };
    });
  },
});

Если добавленная сущность должна оказаться в середине списка, проще инвалидировать только соответствующий диапазон: utils.invalidateQueries({ queryKey: ['messages', userId] }).
При удалении элемента из середины страницы лучше копировать массив (structuralSharing: (oldData, newData) => newData по умолчанию уже оптимизирует, но глубокие мутации делайте иммутабельно).

Управление состоянием загрузки

isFetching (offset) и isFetchingNextPage (infinite) можно использовать для compact-индикаторов в кнопке или в тулбаре.
В v5 fetchNextPage возвращает промис — можно await fetchNextPage() в обработчике и ловить ошибки локально.
retry: false на бесконечной кнопке удобно комбинировать с ручным toast, чтобы не спамить запросы, пока пользователь не нажмёт «Повторить».

Типичные подводные камни

Дубли в списке: хэшируйте курсоры (пример: cursor=lastItem.updatedAt+id) или фильтруйте Set-ом при мердже страниц.
Зависимость от pageSize: при изменении pageSize сбрасывайте queryKey целиком, иначе кешированные страницы будут неконсистентны.
Смена пользователя/тенанта: добавляйте tenantId в queryKey, даже если backend фильтрует по токену.
Рандомный порядок данных: задавайте sort на уровне API — TanStack Query не гарантирует порядок между страницами, если API возвращает их непоследовательно.

Полезные утилиты и лайфхаки

Вынесите генераторы queryOptions (messagesQuery, ticketsQuery) и используйте их и в prefetch*, и в use*Query, чтобы избежать рассинхрона.
Используйте meta: { persist: true } с @tanstack/query-persist-client — бесконечные списки восстанавливаются даже после перезагрузки.
Для мобилок блокируйте множественные fetchNextPage, пока предыдущий промис не завершился (например, с помощью useRef).
Комбинируйте select с useMemo, чтобы из data.pages сразу строить flatList, totalCount, groupedByDate и т. д., минимизируя перерасчёты.
Тестируйте edge-кейсы: пустой список (нет hasNextPage), одна страница, долгие ответы, скачки курсора назад.