componentes / gallery

Gallery

Grade responsiva de miniaturas que abre um visualizador em tela cheia.

Como usar

Passe `items` (`src`, `alt`, `thumbnail` e `caption` opcionais). Cada miniatura é um botão que abre o `Lightbox` naquela imagem; o foco volta para a miniatura ao fechar. Controle a grade com `columns`, `gap` e `aspectRatio`, ou desligue o visualizador com `lightbox={false}` e use `onItemClick`.

preview

Gallery.tsx

import { Gallery } from "vaiperui";
 
<Gallery
  aria-label="Fotos da viagem"
  columns={3}
  items={[
    { src: "/photos/road.jpg", alt: "Mountain road", caption: "Road" },
    { src: "/photos/sky.jpg", alt: "Starry sky", thumbnail: "/photos/sky-sm.jpg" },
  ]}
/>

Colunas

preview

colunas.tsx

<Gallery columns={2} items={items} />
<Gallery columns={4} aspectRatio="1 / 1" items={items} />

Radius e espaçamento

preview

radius.tsx

<Gallery radius="none" gap={2} items={items} />
<Gallery radius="lg" gap={16} items={items} />

Sem visualizador

preview

sem-visualizador.tsx

<Gallery lightbox={false} onItemClick={(item, i) => select(i)} items={items} />

Props

Prop	Valores	Padrão	Descrição
items	{ src, alt, thumbnail?, caption? }[]	—	Imagens. `thumbnail` vai na grade, `src` no visualizador
columns	number	3	Colunas da grade
gap	number	8	Espaço entre miniaturas, em px
aspectRatio	string	4 / 3	Proporção CSS de cada miniatura
lightbox	boolean	true	Abrir o visualizador ao clicar
onItemClick	(item, index) => void	nenhum	Chamado a cada clique em uma miniatura
openLabel	(item, index) => string	Open image N: alt	Nome acessível de cada botão de miniatura
lightboxProps	{ label, closeLabel, previousLabel, nextLabel, counterLabel }	nenhum	Textos do visualizador
radius	none \| sm \| md \| lg \| full	md	Arredondamento das miniaturas
animation	none \| smooth \| fast \| bounce	smooth	Transição do zoom ao passar o mouse
aria-label	string	nenhum	Descreve a lista de imagens

Acessibilidade

Os itens formam uma lista (`<ul aria-label>`) e cada miniatura é um `<button>` real, alcançável com Tab e ativado com Enter ou Espaço.
Cada botão é nomeado por `openLabel(item, index)`, que por padrão é `Open image N: <alt>`.
`alt` é obrigatório em cada item e é usado na miniatura e no visualizador.
A legenda de hover também aparece quando o botão tem foco do teclado.
Com `lightbox`, o clique abre o `Lightbox` (um diálogo modal); sem ele, os botões só chamam `onItemClick`.

Teclado

Tecla	Ação
Tab	Percorre as miniaturas
Enter / Space	Abre a imagem no visualizador

Tenha em mente

Escreva um `alt` real para cada imagem (descreva-a); o componente não valida isso.
Passe `aria-label` para a lista e traduza `openLabel` para o idioma da página.