MediaGenerated from the public API

ImageGallery

A grid that opens into a lightbox without losing your place.

@luc/ui

Examples

Default

Four figures on a video aspect; the caption is the accessible name's companion, not a replacement for it.

<ImageGallery
  images={shots}
  label="Figures"
  columns={4}
  aspect="video"
/>

Usage

import { ImageGallery } from "@luc/ui";

<ImageGallery
  images={images}
  columns={3}
  label="Field notes"
  lightbox
/>

Package setup — peer requirements, the stylesheet and the provider — is on installation.

API

Read from the published TypeScript API, so a prop that is not listed here does not exist and a default that is listed is the one the compiler sees.

Exported symbols
Export	Kind	Signature
`ImageGallery`	6 documented props	`({ images, columns, label, onOpen, lightbox, aspect, className, ...props }: ImageGalleryProps) => import("@types/react").JSX.Element`
`Lightbox`	7 documented props	`({ images, index, open, onOpenChange, onIndexChange, label, labels, }: LightboxProps) => import("@types/react").JSX.Element \| null`

ImageGallery props

Type: ImageGalleryProps

Values the compiler reads from the declaration.

ImageGallery props
Prop	Type	Default	Notes
`aspect?`	`"video" \| "square" \| "natural" \| undefined`	`—`
`columns?`	`2 \| 4 \| 3 \| undefined`	`—`
`images`	`readonly GalleryImage[]`	`—`
`label?`	`string \| undefined`	`—`	Accessible name for the group.
`lightbox?`	`boolean \| undefined`	`—`	Open the built-in lightbox on click. Default `true` unless `onOpen` is set.
`onOpen?`	`((index: number) => void) \| undefined`	`—`	Disable the built-in viewer and handle activation yourself.

Type: LightboxProps

Values the compiler reads from the declaration.

Lightbox props
Prop	Type	Default
`images`	`readonly GalleryImage[]`	`—`
`index`	`number`	`—`
`label?`	`string \| undefined`	`—`
`labels?`	`LightboxLabels \| undefined`	`—`
`onIndexChange`	`(index: number) => void`	`—`
`onOpenChange`	`(open: boolean) => void`	`—`
`open`	`boolean`	`—`

Guidelines

Give every image an `alt` that says what it shows; a gallery of empty alt text is a gallery of nothing.
Turn on `lightbox` for photographs the reader will want full size, and keep `columns` at two when the images carry detail.

Don't

Use the gallery as a layout for unrelated cards; it is a set of images, and the list semantics say so.

Accessibility

The gallery is a named list of images, and the lightbox is a modal with its own labels, a live zoom announcement and a close control. Focus returns to the thumbnail that opened it.