Rolagem Infinita
Regras
- Paginação baseada em cursor: use o ID ou timestamp do último item como cursor — não use offset, que quebra com inserções/exclusões
- IntersectionObserver: anexe a um elemento sentinela no final da lista — dispare a busca quando visível
- Virtualização:
@tanstack/react-virtual para listas com 1.000+ itens — renderiza apenas as linhas visíveis no DOM
- Esqueleto de carregamento: mostre placeholders no final enquanto busca a próxima página — não um spinner
- Botão "Carregar mais": forneça como alternativa para usuários que preferem controle manual ou têm conexões lentas
- Restauração da posição de rolagem: salve a posição antes da navegação, restaure ao voltar — use
sessionStorage ou estado do roteador
- Estado vazio: mostre uma mensagem quando a lista estiver vazia — não uma página em branco
- Fim da lista: mostre "Você chegou ao fim" quando
hasNextPage for false — pare o observer
Padrões
import { useInfiniteQuery } from "@tanstack/react-query";
import { useRef, useEffect } from "react";
function InfiniteList() {
const sentinelRef = useRef<HTMLDivElement>(null);
const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
queryKey: ["items"],
queryFn: ({ pageParam }) => fetchItems({ cursor: pageParam, limit: 20 }),
getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
initialPageParam: undefined as string | undefined,
});
useEffect(() => {
const observer = new IntersectionObserver(
(entries) => { if (entries[0].isIntersecting && hasNextPage) fetchNextPage(); },
{ rootMargin: "200px" }
);
if (sentinelRef.current) observer.observe(sentinelRef.current);
return () => observer.disconnect();
}, [hasNextPage, fetchNextPage]);
const allItems = data?.pages.flatMap((page) => page.items) ?? [];
return (
<div>
{allItems.map((item) => <ItemCard key={item.id} item={item} />)}
{isFetchingNextPage && <LoadingSkeleton count={3} />}
{!hasNextPage && allItems.length > 0 && <p>Você chegou ao fim</p>}
{allItems.length === 0 && !isFetchingNextPage && <EmptyState />}
<div ref={sentinelRef} />
</div>
);
}
import { useVirtualizer } from "@tanstack/react-virtual";
function VirtualList({ items }: { items: Item[] }) {
const parentRef = useRef<HTMLDivElement>(null);
const virtualizer = useVirtualizer({
count: items.length,
getScrollElement: () => parentRef.current,
estimateSize: () => 64,
overscan: 5,
});
return (
<div ref={parentRef} style={{ height: "600px", overflow: "auto" }}>
<div style={{ height: `${virtualizer.getTotalSize()}px`, position: "relative" }}>
{virtualizer.getVirtualItems().map((virtualRow) => (
<div key={virtualRow.key} style={{
position: "absolute", top: 0, left: 0, width: "100%",
transform: `translateY(${virtualRow.start}px)`,
}}>
<ItemCard item={items[virtualRow.index]} />
</div>
))}
</div>
</div>
);
}
Evite
- Paginação baseada em offset — inserções/exclusões deslocam todos os offsets, causando duplicação ou itens faltantes
- Carregar todos os itens e filtrar no cliente — busque apenas a página atual do servidor
- Renderizar 10k+ nós DOM — use
@tanstack/react-virtual para renderizar apenas as linhas visíveis
- IntersectionObserver sem
rootMargin — adicione margem de 100-200px para pré-carregar antes do usuário chegar ao final
- Indicador de fim de lista ausente — os usuários precisam saber que não há mais nada para carregar