Guia para React

Aprenda a montar sliders com @reelkit/react.

Componente Reel

O componente Reel é o contêiner principal: cuida do estado do slider, dos gestos de toque, da navegação por teclado e das animações.

Dimensionamento automático

A prop size é opcional. Sem ela, o Reel mede o próprio contêiner com ResizeObserver e acompanha o layout definido no CSS. O contêiner precisa ganhar tamanho do elemento pai (flex, grid ou dimensões explícitas no CSS).

Padrão itemBuilder

A prop itemBuilder é uma função que recebe o índice e devolve o conteúdo de cada slide. Esse padrão é o que viabiliza a virtualização — apenas os itens visíveis são renderizados.

Navegação

Formas de navegação já incluídas:

Estado na URL

useOverlayUrlState monta um controlador de estado na URL para o overlay e devolve o controlador inteiro; você o entrega a um *UrlOverlay pela prop controller. Quem manda no estado aberto é a URL, então um overlay ligado a ela se abre sozinho e o link vira a forma normal de abrir. A primeira escrita de um parâmetro ausente empilha uma entrada no histórico e cada escrita seguinte a substitui, então percorrer os itens nunca soterra o botão voltar. Guarde o controlador para ler value/position e para conduzi-lo por código: set(position) abre, set(null) fecha, e set é exatamente a mesma escrita de baixo nível que o overlay usa internamente ao trocar de slide.

O objeto de opções recebe param, codec e locator (os três obrigatórios), mais um adapter opcional. param e adapter são lidos na primeira renderização e ficam fixos depois disso — remonte o componente para trocá-los —, enquanto codec e locator são lidos ao vivo, então uma busca feita depois de a lista crescer ou mudar de ordem enxerga a lista atual. O codec e o locator formam um par combinado que divide o mesmo Id, por isso andam juntos — em uma galeria simples com ?photo=3, espalhe ...urlIndexKey(() => images.length), que devolve as duas metades de uma vez. urlIndexKey liga o parâmetro a um índice de slide e o limita pela contagem atual que o getter devolve, então um ?photo=99 velho ou fora do intervalo é rejeitado e se cura sozinho saindo da URL, em vez de abrir um slide que ninguém nomeou. Passe um getter, e não um número, para que o limite continue certo à medida que um feed paginado cresce. Por baixo, ele embrulha createIndexLocator (a metade do locator) e a combina com indexCodec. Um feed paginado ou uma galeria endereçada por identidade fornece o próprio par codec + locator. A tabela completa de opções está na referência da API para React.

ReelIndicator

Componente opcional que mostra indicadores de progresso no estilo Instagram, sinalizando a posição atual dentro do slider. Colocado dentro de um Reel, ele se liga sozinho aos valores de count e active do componente pai pelo contexto — sem estado ligado à mão.

Demonstração ao vivo: slider básico

Experimente — clique nos botões para percorrer os slides.

Pontos principais

• prop size

  Tupla [largura, altura] opcional; sem ela, o tamanho vem do CSS

• itemBuilder

  Recebe o índice e devolve o conteúdo do slide

• apiRef

  Dá acesso aos métodos do controlador para navegar

• afterChange

  Acompanha o índice atual para atualizar a interface

Demonstração ao vivo: lista infinita

O reelkit mantém apenas 3 slides no DOM a qualquer momento (atual, anterior, próximo). É isso que deixa a rolagem fluida em listas com mais de 10.000 itens.

10.000 itens — apenas 3 no DOM. Use os botões ou digite um número para saltar.

Demonstração ao vivo: lista que cresce

Simula um feed infinito em que os itens chegam conforme a necessidade — como no TikTok ou no Instagram. Comece com 20 itens, role até perto do fim e veja novos lotes chegarem sozinhos.

Role até o fim — novos itens chegam sozinhos. O contador e o indicador crescem a cada lote.

Dicas de desempenho

• Memorize os arrays de dados

  Envolva seu array de itens com useMemo. Uma nova referência de array a cada renderização dispara uma atualização de count e o recálculo dos intervalos visíveis.

• Deixe o itemBuilder leve

  Ele roda a cada mudança do intervalo visível (normalmente 3 slides). Evite cálculos pesados ou efeitos colaterais lá dentro.

• Carregue os dados perto da borda

  Use afterChange para perceber quando o leitor se aproxima do fim e busque o lote seguinte antes que os slides acabem (veja a demonstração da lista que cresce, acima).

• Desligue a roda em páginas roláveis

  Defina enableWheel={false} quando o slider estiver dentro de um layout rolável, para não capturar a rolagem da página.