Unendliches Scrollen
Regeln
- Cursor-basierte Paginierung: Verwende die ID oder den Zeitstempel des letzten Elements als Cursor – nicht den Offset, der bei Einfügungen/Löschungen bricht.
- IntersectionObserver: Befestige ihn an einem Wächter-Element am unteren Ende der Liste – löse das Abrufen aus, wenn es sichtbar wird.
- Virtualisierung:
@tanstack/react-virtual für Listen mit 1.000+ Elementen – rendert nur sichtbare Zeilen im DOM.
- Lade-Skelett: Zeige Platzhalter-Elemente am unteren Ende während des Abrufens der nächsten Seite an – keinen Spinner.
- „Mehr laden“-Button: Stelle diesen als Fallback für Benutzer bereit, die manuelle Steuerung bevorzugen oder langsame Verbindungen haben.
- Wiederherstellung der Scrollposition: Speichere die Scrollposition vor der Navigation, stelle sie beim Zurückkehren wieder her – verwende
sessionStorage oder den Router-Status.
- Leerer Zustand: Zeige eine Nachricht an, wenn die Liste null Elemente enthält – keine leere Seite.
- Ende der Liste: Zeige „Du hast das Ende erreicht“ an, wenn
hasNextPage false ist – stoppe den Observer.
Muster
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>Du hast das Ende erreicht</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>
);
}
Vermeiden
- Offset-basierte Paginierung – Einfügungen/Löschungen verschieben alle Offsets, was zu doppelten oder fehlenden Elementen führt.
- Laden aller Elemente und dann clientseitiges Filtern – rufe nur die aktuelle Seite vom Server ab.
- Rendern von 10k+ DOM-Knoten – verwende
@tanstack/react-virtual, um nur sichtbare Zeilen zu rendern.
- IntersectionObserver ohne
rootMargin – füge einen Rand von 100–200px hinzu, um vorzuladen, bevor der Benutzer den unteren Rand erreicht.
- Fehlender End-of-List-Indikator – Benutzer müssen wissen, dass es nichts mehr zu laden gibt.