Image Gallery
A grid of thumbnails that open a viewer with previous and next.Basic
Preview
Code
Installation
Package
CLI (copy source)
pnpm
pnpm add @advui/corenpm
npm install @advui/coreUsage
import { ImageGallery } from '@advui/core'
<ImageGallery
images={[{ src: photo.url, thumbnail: photo.thumbUrl, alt: 'Clinic entrance', caption: 'Opened in June' }]}
/>API reference
ImageGallery
| Prop | Type | Default | Description |
|---|---|---|---|
images required | GalleryImage[] | — | `{ src, alt, caption?, thumbnail? }`. `alt` is required. |
columns | numberor a breakpoint map | { base: 2, sm: 3 } | Thumbnails per row, mobile first. |
ratio | number | 1 | Thumbnail shape (width / height). |
index | number | null | — | The image open in the viewer; `null` when closed. |
defaultIndex | number | null | — | Starting `index` when uncontrolled. |
onIndexChange | (index: number | null) => void | — | Called with the new `index`. |
labels | Partial<ImageGalleryLabels> | — | Button names and "3 of 12", for translation. |
Accessibility
- Each thumbnail is a button named "View {alt}"; the thumbnail picture inside is decorative.
- The viewer is a modal dialog titled with the image’s
alt; the image keeps itsalt, the caption describes the dialog, and "2 of 6" is a polite live region. - Previous and next are named buttons, disabled at the ends; focus returns to the thumbnail on close.
| Key | Action |
|---|---|
| Enter / Space | Opens the focused thumbnail. |
| Arrow Left / Arrow Right | Previous or next image (web). |
| Escape | Closes the viewer. |
Responsive behavior
The grid follows columns; the viewer fits the screen and keeps the image’s shape.
Platform notes
Web
Pass smaller
thumbnail URLs so the grid loads fast.iOS
Swipe is not wired; use the previous and next buttons.
Android
Same as iOS; the back button closes the viewer.