YepAPI/skills - Défilement Infini

Défilement Infini

Règles

• Pagination basée sur curseur : utilisez l'ID ou le timestamp du dernier élément comme curseur — pas de décalage (offset), qui casse lors des insertions/suppressions.
• IntersectionObserver : attachez-le à un élément sentinelle en bas de la liste — déclenchez le chargement quand il devient visible.
• Virtualisation : @tanstack/react-virtual pour les listes de 1 000+ éléments — ne rend que les lignes visibles dans le DOM.
• Squelette de chargement : affichez des éléments placeholders en bas pendant le chargement de la page suivante — pas de spinner.
• Bouton "Charger plus" : proposez-le comme alternative pour les utilisateurs qui préfèrent un contrôle manuel ou ont une connexion lente.
• Restauration de la position de défilement : sauvegardez la position avant la navigation, restaurez-la au retour — utilisez sessionStorage ou l'état du routeur.
• État vide : affichez un message lorsque la liste ne contient aucun élément — pas une page blanche.
• Fin de liste : affichez "Vous avez atteint la fin" quand hasNextPage est false — arrêtez l'observateur.

Modèles

// Défilement infini avec React Query + IntersectionObserver
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" } // pré-chargement avant d'atteindre le bas
    );
    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>Vous avez atteint la fin</p>}
      {allItems.length === 0 && !isFetchingNextPage && <EmptyState />}
      <div ref={sentinelRef} />
    </div>
  );
}

// Liste virtualisée pour 10 000+ éléments
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, // hauteur estimée d'une ligne en px
    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>
  );
}

À éviter

• Pagination basée sur offset — les insertions/suppressions décalent tous les offsets, provoquant des doublons ou des éléments manquants.
• Charger tous les éléments puis filtrer côté client — ne récupérez que la page courante depuis le serveur.
• Rendre 10 000+ nœuds DOM — utilisez @tanstack/react-virtual pour ne rendre que les lignes visibles.
• IntersectionObserver sans rootMargin — ajoutez une marge de 100 à 200 pixels pour précharger avant que l'utilisateur n'atteigne le bas.
• Absence d'indicateur de fin de liste — les utilisateurs doivent savoir qu'il n'y a plus rien à charger.