Referência da API para React

Referência completa dos componentes, das props e dos métodos de @reelkit/react.

Props do Reel

ReelProps

Callbacks

Métodos do ReelApi

Alcance os métodos do slider pelo apiRef:

const apiRef = useRef<ReelApi>(null);

// Navigation
apiRef.current?.next();
apiRef.current?.prev();
apiRef.current?.goTo(5);           // instant
apiRef.current?.goTo(5, true);     // animated

// Lifecycle
apiRef.current?.adjust();          // recalculate positions
apiRef.current?.observe();         // start observing keyboard
apiRef.current?.unobserve();       // stop observing keyboard

Props do ReelIndicator

ReelIndicatorProps

Componentes observadores

Observe

Faz a ponte entre os sinais do core e a renderização do React sem provocar re-renderizações no componente pai. Só a função dos filhos roda de novo quando os sinais assinados mudam.

import { Observe } from '@reelkit/react';

<Observe signals={[controller.state.index]}>
  {() => <span>Current: {controller.state.index.value}</span>}
</Observe>

AnimatedObserve

Assina sinais de valor animado e interpola suavemente usando requestAnimationFrame.

import { AnimatedObserve } from '@reelkit/react';

<AnimatedObserve signal={controller.state.axisValue}>
  {(value) => (
    <div style={{ transform: `translateY(${value}px)` }} />
  )}
</AnimatedObserve>

SwipeToClose

<SwipeToClose> envolve os filhos num contêiner que acompanha um deslize vertical e chama onClose quando o deslize passa do limiar — o gesto de fechar do Lightbox e do Stories Player, para um overlay próprio. SwipeToCloseProps tipa as props; SwipeToCloseDirection é 'up' | 'down'.

SoundProvider

<SoundProvider> cria um SoundController, mudo no início, e o entrega aos filhos por meio de useSoundState. Os overlays já renderizam um para você; adicione o seu apenas em volta de um player próprio cujos controles compartilham o estado do som.

Hooks

useBodyLock

Trava a rolagem do corpo e compensa o deslocamento causado pela largura da barra de rolagem.

import { useBodyLock } from '@reelkit/react';

// Lock body scroll when overlay is open
useBodyLock(isOpen);

useOverlayUrlState

OverlayUrlStateOptions

Monta um controlador de estado na URL para o overlay, que você entrega a um *UrlOverlay pela prop controller.

Veja Estado na URL no guia para React para o passo a passo e os exemplos.

useReactRouterUrlAdapter

Um UrlAdapter apoiado no React Router. Passe-o na opção adapter de useOverlayUrlState em um app com rotas, para que o roteador siga sendo a única fonte de verdade da navegação — escrever history.pushState por trás dele deixa sua localização desatualizada, e a navegação seguinte derruba o parâmetro. As escritas mexem apenas na consulta, então o caminho e o hash seguem intactos. Cada mudança informa se o roteador empilhou na mesma página, substituiu ou andou pelo histórico, de modo que uma galeria aberta por um <Link> fecha com um único passo para trás.

Vem de um subcaminho próprio, então um app sem roteador nunca puxa react-router-dom para o bundle. react-router-dom é uma peer dependency opcional.

import { useReactRouterUrlAdapter } from '@reelkit/react/react-router-url-adapter';

const adapter = useReactRouterUrlAdapter();
const photo = useOverlayUrlState({
  param: 'photo',
  adapter,
  ...urlIndexKey(() => images.length),
});

useReelContext

useReelContext() lê o ReelContextValue do <Reel> pai mais próximo, ou devolve null fora de um. O <ReelIndicator> o usa para se conectar; use-o nos seus próprios controles renderizados como filhos do <Reel>, para que acompanhem o slider sem props. ReelContext é o objeto de contexto por trás dele — forneça um valor seu apenas num teste ou num wrapper próprio.

useSoundState

useSoundState() lê o SoundController do <SoundProvider> mais próximo e lança um erro fora de um. O Reel Player, o Lightbox e o Stories Player envolvem o conteúdo num provider, então os controles próprios que você passa pelas render props deles podem chamá-lo para ler ou alternar o som.

useFullscreen

useFullscreen({ ref }) controla a Fullscreen API para o elemento em ref e sai da tela cheia quando o componente é desmontado. UseFullscreenProps é o argumento; UseFullscreenResult é a tupla que ele devolve.

Acessibilidade

<Reel> é renderizado como role="region" com aria-roledescription="carousel". Defina a prop ariaLabel para dar à região um nome que o leitor de tela anuncie. Uma live region educada anuncia "Slide N de M" a cada troca, sem re-renderizar o carrossel. Os slides inativos recebem o atributo inert, então o foco e a navegação por tecnologia assistiva passam por cima deles.

<ReelIndicator> é renderizado como role="tablist", com tabindex móvel nos pontos; as setas movem o foco e Enter ou Espaço ativa o slide.

Montando um modal próprio em volta de <Reel>? captureFocusForReturn, createFocusTrap e getFocusableElements são reexportados por @reelkit/react para devolver e prender o foco.

Utilitários

createDefaultKeyExtractorForLoop

Cria um extrator de chaves que dá conta dos índices repetidos quando loop está ligado.

import { createDefaultKeyExtractorForLoop } from '@reelkit/react';

<Reel
  count={items.length}
  size={size}
  loop
  keyExtractor={createDefaultKeyExtractorForLoop(items.length)}
  itemBuilder={...}
/>

Detecção de tamanho

observeElementSize, getViewportSize, observeViewportSize, isMobileWidth, fitAspectRatio e isTouchDevice são reexportados por @reelkit/react, para um overlay próprio que se dimensione do mesmo jeito que os do reelkit. Veja Detecção de tamanho na API do core.

Reprodução automática e download

createTimerController, createSlideshowController e downloadFile também são reexportados por @reelkit/react: o timer por trás dos players de stories, a apresentação por trás do autoAdvance do lightbox e o helper por trás do seu botão de download. Veja Reprodução automática e Download na API do core.