Lightbox

Uma galeria de imagens e vídeos em tela cheia, com @reelkit/react-lightbox.

Ver demonstração ao vivo →

Recursos

Instalação

Não esqueça de importar os estilos:

Início rápido

O componente LightboxOverlay mostra imagens em tela cheia. Passe um array de objetos LightboxItem e controle a visibilidade com um índice que aceita nulo.

Demonstração ao vivo

Clique em uma miniatura para abrir a galeria. Use as setas ou deslize para navegar.

Slides de vídeo (opcionais)

O suporte a vídeo é inteiramente opcional e sai no tree-shaking — quem usa só imagens não paga nada a mais no bundle. Importe useVideoSlideRenderer e ligue o que ele devolve ao LightboxOverlay. O hook cuida sozinho dos estados de carregamento, do som e do ciclo de vida do vídeo.

Personalização

Controles próprios

Use renderControls para substituir o botão de fechar, o contador e o botão de tela cheia padrão. Componha com os subcomponentes exportados:

Camada de informações própria

Use renderInfo para substituir o gradiente padrão de título e descrição, ou passe renderInfo={() => null} para escondê-lo por completo:

Navegação própria

Use renderNavigation para substituir as setas padrão de avançar e voltar:

Slide próprio

Use renderSlide para um conteúdo de slide totalmente seu. Devolva null para cair no slide de imagem padrão:

Carregamento de conteúdo e tratamento de erros

A galeria acompanha o carregamento e os erros de cada slide. Um girador aparece enquanto o conteúdo carrega; um ícone de imagem quebrada aparece quando a mídia falha. As URLs com erro ficam em cache, então voltar a elas mostra o erro na hora, sem nova tentativa.

Callbacks de ciclo de vida

Ao usar renderSlide, chame estes callbacks para comandar o indicador de carregamento:

Interface própria de carregamento e erro

Troque o girador e o ícone de erro padrão por componentes seus:

Estado na URL

Ver demonstração ao vivo →

LightboxUrlOverlay é um componente à parte cujo estado aberto vive na barra de endereços. Monte um controlador com useOverlayUrlState, de @reelkit/react, e entregue-o como controller: a galeria se abre quando o parâmetro nomeia um slide e se fecha quando ele some. Os links dão para compartilhar, e o botão voltar fecha a galeria em vez de sair da página.

O hook recebe um objeto de opções e devolve um UrlStateController (com set, index, value). Guarde-o para o controle programático: set é a escrita de baixo nível que o overlay usa internamente (troca de slide, e set(null) para fechar). Ele também conduz o overlay por código — set(index) o abre, exatamente como navegar até o parâmetro. Ainda assim, prefira um link para abrir: o href dá para compartilhar, abre em nova aba e o botão voltar o fecha — tudo de graça, sem nenhum handler.

As opções completas de useOverlayUrlState (param, adapter, codec, locator) estão na referência da API para React.

O próprio LightboxUrlOverlay recebe apenas controller (obrigatório), um onClose opcional e todas as props visuais e de comportamento que o LightboxOverlay aceita (images, ariaLabel, transitionFn, as render props e assim por diante) — mas nenhum isOpen.

• Abrir custa uma entrada no histórico. Percorrer os slides a substitui, então cem deslizes não acrescentam nenhuma — um único passo para trás sempre sai da galeria. Voltar fecha; não passa de foto em foto.
• Um link compartilhado como ?photo=3 abre a galeria naquele slide. Fechar um link que chegou junto com a página remove o parâmetro ali mesmo, em vez de tirar o leitor do seu site.
• Voltar só fecha quando você abriu de dentro do app — o link empilhou uma entrada, então voltar desempilha até a galeria. Um link compartilhado aberto direto em uma aba nova não tem histórico atrás de si, então o voltar do navegador sai do site; o botão de fechar ou o Escape removem o parâmetro ali mesmo e mantêm você na galeria. Os adaptadores de roteador que acompanham o pacote atestam um empilhamento na mesma página; um adaptador próprio que não sabe dizer como a entrada chegou recebe o fechamento no lugar, o que deixa uma cópia da página no histórico — um passo para trás parece então não fazer nada, mas nada reabre.
• Um parâmetro que não nomeia slide nenhum — um favorito velho, um valor editado à mão — é retirado da URL, em vez de deixar a barra de endereços afirmando um slide que não abre.

Em um app com rotas, passe um adaptador. Escrever direto no histórico deixa a localização do roteador desatualizada, e a navegação seguinte derruba o parâmetro.

Abrir é um link. Como o estado aberto vive na URL, a miniatura é um link comum — sem handler de clique — e o comportamento nativo do navegador vem junto: abrir em nova aba, copiar o endereço, pré-visualizar ao passar o mouse. Em um app com rotas, use o link do roteador para que a navegação siga no cliente.

Prefira uma identidade estável nos links compartilhados. O índice é posicional, então um ?photo=3 favoritado abre outra imagem assim que a lista muda de ordem. urlStableIdKey usa o id estável de cada item, varrendo a lista atual — uma chamada resolve o caso comum.

Passe hashCodec: base64UrlCodec para escrever o id em base64url na URL — é um disfarce reversível, não um hash criptográfico.

Quer endereçar por outro campo (um slug), ou paginar um feed infinito com locateAsync? Monte o codec e o locator você mesmo:

Galerias infinitas ou paginadas. O locate síncrono só responde pelas imagens já carregadas — um link compartilhado para a imagem 400 de um feed que carregou 20 volta vazio. locateAsync é o plano B, chamado somente quando locate falha.

• A forma de carregar é escolha sua — busque páginas contíguas até o alvo, ou busque só aquela imagem e a acrescente. A URL endereça por identidade, não por posição, então findIndex devolve onde quer que o item tenha caído.
• Enquanto locateAsync está pendente, a galeria fica fechada e o parâmetro é deixado em paz, então o link direto sobrevive à busca. Um null ou uma rejeição derrubam o parâmetro.
• Uma resposta que chega depois de a URL ter mudado, depois de um fechamento ou depois da desmontagem é descartada — uma busca lenta não pode abrir um slide que ninguém pediu.
• Nada é renderizado enquanto a busca corre; esse estado de carregamento já pertence à página, então desenhe o seu próprio esqueleto.
• Não existe tempo limite — a galeria não tem como saber o próprio tamanho. Termine com null quando a paginação se esgotar, ou o overlay fica fechado para sempre.
• O que locateAsync devolver é palavra final — o índice dos dados que ele acabou de buscar, tomado como está, sem reler images.

Referência da API

Props do LightboxOverlay

LightboxOverlayProps

Props do LightboxUrlOverlay

LightboxUrlOverlayProps

Aceita todas as props visuais e de comportamento acima, menos isOpen, substituída por controller. initialIndex é ignorada aqui — quem escolhe o slide é a posição do controlador, então um valor passado ao lado dela seria sobrescrito a cada abertura.

Callbacks

Props do Reel (repassadas)

Estas props são repassadas ao componente Reel por baixo.

Tipos

LightboxItem

ControlsRenderProps

NavigationRenderProps

SlideRenderProps

InfoRenderProps

Subcomponentes

Subcomponentes reutilizáveis para compor controles próprios com renderControls.

CloseButton

O botão X de fechar padrão.

Counter

Pílula contadora de imagens, mostrando "1 / 3".

FullscreenButton

Botão de tela cheia (ícone de maximizar/minimizar).

SoundButton

Botão de mudo para os slides de vídeo (ícone Volume2/VolumeX). Vem incluído automaticamente no renderControls de useVideoSlideRenderer. Para usá-lo isolado dentro de controles próprios, alcance o estado do som por useSoundState.

Hooks

useVideoSlideRenderer

Hook do suporte opcional a vídeo. Devolve renderSlide, renderControls e SoundProvider — envolva o overlay no SoundProvider e passe as funções de renderização.

useFullscreen

Hook para controlar o estado de tela cheia com suporte entre navegadores.

Transições

Passe qualquer TransitionTransformFn pela prop transitionFn. Importar apenas a transição que você usa deixa o bundler descartar as outras. Sem esta prop, vale slideTransition.

Função de transição própria

Escreva a sua TransitionTransformFn e passe-a por transitionFn. A assinatura é a mesma das transições do slider do core.

Classes CSS

Todos os elementos da interface usam classes CSS simples (não são CSS modules), que dá para alcançar com seletores de especificidade maior em uma folha de estilo carregada depois de @reelkit/react-lightbox/styles.css. Para mudar cor, tamanho e z-index, prefira as propriedades CSS documentadas na seção Temas, abaixo.

Temas

Cada cor, tamanho, z-index e transição vive em uma propriedade CSS. Sobrescreva uma ou várias em :root (ou em qualquer ancestral da galeria) para trocar o tema sem mexer no código dos componentes.

Cole o trecho abaixo em uma folha de estilo carregada depois de @reelkit/react-lightbox/styles.css.

Acessibilidade

A raiz do overlay é um diálogo modal (role="dialog", aria-modal="true"). Defina ariaLabel para mudar o que o leitor de tela anuncia; o padrão é "Image gallery". Cada slide carrega role="group", aria-roledescription="slide" e aria-label="Image N of M".

A galeria captura o foco ao abrir e o devolve ao gatilho ao fechar. Tab e Shift+Tab percorrem os elementos focáveis lá dentro; um foco que escapa (clique fora, foco por código) é trazido de volta. Implementado com captureFocusForReturn e createFocusTrap, de @reelkit/core.

Atalhos de teclado