Mídia e pessoas

VImageGallery

Componentev-model7 exemplos9 propsA2UI · ImageGallery

Exibir coleções de imagens num layout limpo e flexível, com apresentação por miniaturas, seleção (simples ou múltipla) e pré-visualização expandida (lightbox) com animações suaves. Casos de uso citados: portfólios, showcases de produto e media libraries. Combina três capacidades: apresentação visual, seleção e expansão.

Importação
<script setup lang="ts">
import { VImageGallery } from 'vueui-nova-kit'
</script>

Uso

Exemplo
<template>
  <VImageGallery
    :images="images"
    layout="grid"
    :selectable="true"
    :multiple="true"
    @select="onSelect" />
</template>

Playground

Os controles abaixo são gerados a partir das props declaradas em VImageGallery.types.ts; o código acompanha cada mudança.

Exemplos

Variantes, tamanhos e estados, extraídos das stories da biblioteca.

Default

Variação Padrão. Estado padrão do componente; use a aba Controls para experimentar as props ao vivo.

Ver código
vue
<script setup lang="ts">
import { VImageGallery } from 'vueui-nova-kit'

const images = [
  {
    src: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
    alt: 'Mountain lake',
  },
  {
    src: 'https://images.unsplash.com/photo-1613395877344-13d4a8e0d49c?w=400&h=400&fit=crop',
    alt: 'Santorini',
  },
  {
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=400&h=400&fit=crop',
    alt: 'Desert palm',
  },
  {
    src: 'https://images.unsplash.com/photo-1552053831-71594a27632d?w=400&h=400&fit=crop',
    alt: 'Golden retriever',
  },
  {
    src: 'https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&h=400&fit=crop',
    alt: 'Forest',
  },
  {
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
    alt: 'Beach',
  },
  {
    src: 'https://images.unsplash.com/photo-1522383225653-ed111181a951?w=400&h=400&fit=crop',
    alt: 'Cherry blossom',
  },
  {
    src: 'https://images.unsplash.com/photo-1480714378408-67cf0d13bc1b?w=400&h=400&fit=crop',
    alt: 'City building',
  },
  {
    src: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=400&fit=crop',
    alt: 'Mountain valley',
  },
]
</script>

<template>
  <VImageGallery v-model="value" :images="images" selectable multiple />
</template>

Hero

Variação Hero. Props: layout="grid", selectable=true, multiple=true.

Ver código
vue
<script setup lang="ts">
import { VImageGallery } from 'vueui-nova-kit'

const images = [
  {
    src: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
    alt: 'Mountain lake',
  },
  {
    src: 'https://images.unsplash.com/photo-1613395877344-13d4a8e0d49c?w=400&h=400&fit=crop',
    alt: 'Santorini',
  },
  {
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=400&h=400&fit=crop',
    alt: 'Desert palm',
  },
  {
    src: 'https://images.unsplash.com/photo-1552053831-71594a27632d?w=400&h=400&fit=crop',
    alt: 'Golden retriever',
  },
  {
    src: 'https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&h=400&fit=crop',
    alt: 'Forest',
  },
  {
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
    alt: 'Beach',
  },
  {
    src: 'https://images.unsplash.com/photo-1522383225653-ed111181a951?w=400&h=400&fit=crop',
    alt: 'Cherry blossom',
  },
  {
    src: 'https://images.unsplash.com/photo-1480714378408-67cf0d13bc1b?w=400&h=400&fit=crop',
    alt: 'City building',
  },
  {
    src: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=400&fit=crop',
    alt: 'Mountain valley',
  },
]
</script>

<template>
  <VImageGallery v-model="value" :images="images" selectable multiple />
</template>

Variants

Variação Variantes.

Ver código
vue
<script setup lang="ts">
import { VImageGallery } from 'vueui-nova-kit'

const images = [
  {
    src: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
    alt: 'Mountain lake'
  },
  {
    src: 'https://images.unsplash.com/photo-1613395877344-13d4a8e0d49c?w=400&h=400&fit=crop',
    alt: 'Santorini'
  },
  {
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=400&h=400&fit=crop',
    alt: 'Desert palm'
  },
  {
    src: 'https://images.unsplash.com/photo-1552053831-71594a27632d?w=400&h=400&fit=crop',
    alt: 'Golden retriever'
  },
  {
    src: 'https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&h=400&fit=crop',
    alt: 'Forest'
  },
  {
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
    alt: 'Beach'
  },
  {
    src: 'https://images.unsplash.com/photo-1522383225653-ed111181a951?w=400&h=400&fit=crop',
    alt: 'Cherry blossom'
  },
  {
    src: 'https://images.unsplash.com/photo-1480714378408-67cf0d13bc1b?w=400&h=400&fit=crop',
    alt: 'City building'
  },
  {
    src: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=400&fit=crop',
    alt: 'Mountain valley'
  }
]
</script>

<template>
  <div style="display:grid;gap:24px">
    <VImageGallery :images="images" layout="grid" data-test-id="docs-image-gallery-variant-grid" />
    <VImageGallery :images="images.slice(0,6)" layout="masonry" data-test-id="docs-image-gallery-variant-masonry" />
    <VImageGallery :images="images" layout="carousel" data-test-id="docs-image-gallery-variant-carousel" />
    <VImageGallery :images="images" layout="grid" selectable multiple data-test-id="docs-image-gallery-variant-selectable" />
  </div>
</template>

Sizes

Variação Tamanhos.

Ver código
vue
<script setup lang="ts">
import { VImageGallery } from 'vueui-nova-kit'

const images = [
  {
    src: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
    alt: 'Mountain lake'
  },
  {
    src: 'https://images.unsplash.com/photo-1613395877344-13d4a8e0d49c?w=400&h=400&fit=crop',
    alt: 'Santorini'
  },
  {
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=400&h=400&fit=crop',
    alt: 'Desert palm'
  },
  {
    src: 'https://images.unsplash.com/photo-1552053831-71594a27632d?w=400&h=400&fit=crop',
    alt: 'Golden retriever'
  },
  {
    src: 'https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&h=400&fit=crop',
    alt: 'Forest'
  },
  {
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
    alt: 'Beach'
  },
  {
    src: 'https://images.unsplash.com/photo-1522383225653-ed111181a951?w=400&h=400&fit=crop',
    alt: 'Cherry blossom'
  },
  {
    src: 'https://images.unsplash.com/photo-1480714378408-67cf0d13bc1b?w=400&h=400&fit=crop',
    alt: 'City building'
  },
  {
    src: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=400&fit=crop',
    alt: 'Mountain valley'
  }
]
</script>

<template>
  <div style="display:grid;gap:24px">
    <VImageGallery :images="images.slice(0,3)" size="sm" data-test-id="docs-image-gallery-size-sm" />
    <VImageGallery :images="images.slice(0,3)" size="md" data-test-id="docs-image-gallery-size-md" />
    <VImageGallery :images="images.slice(0,3)" size="lg" data-test-id="docs-image-gallery-size-lg" />
  </div>
</template>

States

Variação Estados.

Ver código
vue
<script setup lang="ts">
import { VImageGallery } from 'vueui-nova-kit'

const images = [
  {
    src: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
    alt: 'Mountain lake'
  },
  {
    src: 'https://images.unsplash.com/photo-1613395877344-13d4a8e0d49c?w=400&h=400&fit=crop',
    alt: 'Santorini'
  },
  {
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=400&h=400&fit=crop',
    alt: 'Desert palm'
  },
  {
    src: 'https://images.unsplash.com/photo-1552053831-71594a27632d?w=400&h=400&fit=crop',
    alt: 'Golden retriever'
  },
  {
    src: 'https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&h=400&fit=crop',
    alt: 'Forest'
  },
  {
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
    alt: 'Beach'
  },
  {
    src: 'https://images.unsplash.com/photo-1522383225653-ed111181a951?w=400&h=400&fit=crop',
    alt: 'Cherry blossom'
  },
  {
    src: 'https://images.unsplash.com/photo-1480714378408-67cf0d13bc1b?w=400&h=400&fit=crop',
    alt: 'City building'
  },
  {
    src: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=400&fit=crop',
    alt: 'Mountain valley'
  }
]
</script>

<template>
  <div style="display:grid;gap:24px;max-width:420px">
    <VImageGallery :images="images.slice(0,1)" data-test-id="docs-image-gallery-state-default" />
    <VImageGallery :images="images.slice(0,1)" selectable :model-value="[0]" data-test-id="docs-image-gallery-state-selected" />
    <VImageGallery :images="[]" data-test-id="docs-image-gallery-state-empty" />
  </div>
</template>

Loading

Variação Carregando. Props: loading=true.

Ver código
vue
<script setup lang="ts">
import { VImageGallery } from 'vueui-nova-kit'

const images = [
  {
    src: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
    alt: 'Mountain lake',
  },
  {
    src: 'https://images.unsplash.com/photo-1613395877344-13d4a8e0d49c?w=400&h=400&fit=crop',
    alt: 'Santorini',
  },
  {
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=400&h=400&fit=crop',
    alt: 'Desert palm',
  },
  {
    src: 'https://images.unsplash.com/photo-1552053831-71594a27632d?w=400&h=400&fit=crop',
    alt: 'Golden retriever',
  },
  {
    src: 'https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&h=400&fit=crop',
    alt: 'Forest',
  },
  {
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
    alt: 'Beach',
  },
  {
    src: 'https://images.unsplash.com/photo-1522383225653-ed111181a951?w=400&h=400&fit=crop',
    alt: 'Cherry blossom',
  },
  {
    src: 'https://images.unsplash.com/photo-1480714378408-67cf0d13bc1b?w=400&h=400&fit=crop',
    alt: 'City building',
  },
  {
    src: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=400&fit=crop',
    alt: 'Mountain valley',
  },
]
</script>

<template>
  <VImageGallery
    v-model="value"
    :images="images"
    selectable
    multiple
    loading />
</template>

Columns

Variação Columns. Props: columns=2.

Ver código
vue
<script setup lang="ts">
import { VImageGallery } from 'vueui-nova-kit'

const images = [
  {
    src: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
    alt: 'Mountain lake',
  },
  {
    src: 'https://images.unsplash.com/photo-1613395877344-13d4a8e0d49c?w=400&h=400&fit=crop',
    alt: 'Santorini',
  },
  {
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=400&h=400&fit=crop',
    alt: 'Desert palm',
  },
  {
    src: 'https://images.unsplash.com/photo-1552053831-71594a27632d?w=400&h=400&fit=crop',
    alt: 'Golden retriever',
  },
  {
    src: 'https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&h=400&fit=crop',
    alt: 'Forest',
  },
  {
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
    alt: 'Beach',
  },
  {
    src: 'https://images.unsplash.com/photo-1522383225653-ed111181a951?w=400&h=400&fit=crop',
    alt: 'Cherry blossom',
  },
  {
    src: 'https://images.unsplash.com/photo-1480714378408-67cf0d13bc1b?w=400&h=400&fit=crop',
    alt: 'City building',
  },
  {
    src: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=400&fit=crop',
    alt: 'Mountain valley',
  },
]
</script>

<template>
  <VImageGallery
    v-model="value"
    :images="images"
    selectable
    multiple
    :columns="2" />
</template>

Acessibilidade

  1. ARIA compliant (role="list" and role="listitem") — contentor com role="list", cada miniatura com role="listitem" (ou option quando selecionável com aria-selected).
  2. Keyboard navigation (Tab, Arrow keys) — Tab alcança miniaturas e controlos da lightbox; setas navegam na grelha e entre imagens.
  3. Screen reader friendly (alt text support) — cada imagem exige alt descritivo; lightbox anuncia "Image n of total" via aria-live/label.
  4. Focus visible — anel de foco azul sempre visível via :focus-visible, nunca removido sem substituto.
  5. Supports selection with ARIA states — seleção exposta com aria-selected/aria-pressed/aria-checked; indicar aria-multiselectable quando múltipla.
  6. High contrast and reduced motion support — overlay/indicador com contraste suficiente em alto contraste; prefers-reduced-motion desativa zoom/fade.

Alvos de toque mínimos 44×44px para fechar/setas/filmstrip; Escape fecha sempre a lightbox.

Props

PropTipoDefaultDescrição
imagesVGalleryImage[][]—
layoutVImageGalleryLayout"grid"—
sizeVImageGallerySize"md"—
selectablebooleanfalse—
multiplebooleanfalse—
modelValuenumber[]——
loadingbooleanfalse—
columnsnumber——
dataTestIdstring——

Events

EventoPayloadDescrição
@select{ indices: number[]; image: { src: string; alt: string } }—
@update:modelValuenumber[]—
@opennumber—
@close——

Slots

SlotProps do slot
#lightboximage

Fonte: src/components/images/VImageGallery/VImageGallery.vue · tipos: src/components/images/VImageGallery/VImageGallery.types.ts