Communitygithub.com

YepAPI/skills

Paginação baseada em cursor, IntersectionObserver, listas virtualizadas com @tanstack/react-virtual e restauração de posição de rolagem.

O que é skills?

Este skill implementa a rolagem infinita (infinite scroll) de forma robusta e eficiente para listas grandes em aplicações web. Utiliza paginação baseada em cursor, evitando os problemas de duplicação e itens faltantes comuns na paginação baseada em offset. Um IntersectionObserver é anexado a um elemento sentinela no final da lista para disparar automaticamente a busca da próxima página quando o usuário rola até o final. Para listas com mais de 1.000 itens, o skill recomenda e fornece um padrão para virtualização com @tanstack/react-virtual, que renderiza apenas as linhas visíveis no DOM, garantindo desempenho mesmo com dezenas de milhares de itens. Além disso, cobre casos de uso como skeletons de carregamento, estado vazio, indicador de fim de lista e restauração da posição de rolagem via sessionStorage ou estado do roteador. O skill suporta qualquer plataforma que utilize React e React Query (TanStack Query), como Claude Code, Cursor, Codex ou assistentes de IA focados em desenvolvimento web. Ele é ideal para feeds de redes sociais, painéis de administração, listas de produtos e qualquer interface que precise exibir grandes volumes de dados de forma fluida.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/YepAPI/skills/tree/HEAD/skills/infinite-scroll

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

// Rolagem infinita com 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é-carrega antes do usuário chegar ao final
    );
    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>
  );
}

// Lista virtualizada para 10k+ itens
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, // altura estimada da linha em 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>
  );
}

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

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

YepAPI/skills

WCAG 2.1 AA — semantic HTML, keyboard navigation, screen readers.

YepAPI/skills

Experiment setup, variant splitting, statistical significance, and feature flag integration.

YepAPI/skills

CRUD generators, data tables, user management, role-based access, and bulk operations.

YepAPI/skills

Monitor what ChatGPT and Gemini say about your brand using YepAPI.

YepAPI/skills

Queue workers with BullMQ/Inngest/Trigger.dev, job retries, dead letter queues, concurrency.

YepAPI/skills

Commander.js, interactive prompts with Clack, spinners, colors, config files, exit codes, and npm publishing.

YepAPI/skills

cmdk integration, Cmd+K trigger, fuzzy search, grouped actions, keyboard navigation, and dynamic action registration.

YepAPI/skills

Content planning with trend and sentiment data from YepAPI.

YepAPI/skills

Content calendar, keyword-driven planning, and content briefs.

YepAPI/skills

Theme switching with CSS variables, system preference detection, next-themes, and persistence.

YepAPI/skills

Threaded comments, @mentions, reactions, moderation queue, optimistic UI, and cursor pagination.

YepAPI/skills

Competitive analysis between domains using YepAPI.

YepAPI/skills

Layout grids, KPI cards, data tables with sorting/filtering, sidebar navigation, and responsive breakpoints.

YepAPI/skills

Data encryption — TLS everywhere, AES-256-GCM for PII, bcrypt passwords, encrypted backups.

YepAPI/skills

Chart patterns with Recharts/Nivo/D3, responsive containers, color scales, and accessibility.

YepAPI/skills

Drizzle schema definition, push vs migrate, type-safe queries, relations, transactions, and prepared statements.

YepAPI/skills

Upload handling, resize/compress, CDN delivery, blur placeholders, and next/image patterns.

YepAPI/skills

Local business and Google Maps research using YepAPI.

YepAPI/skills

Tenant isolation (row-level vs schema), subdomain routing, per-tenant config, and data partitioning.

YepAPI/skills

Chat UI components, streaming responses with AI SDK, context window management, and RAG patterns.

Habilidades Relacionadas