Lightbox / Image Zoom

Thumbnail grid that opens a full-screen viewer: arrow keys / buttons to navigate, Z to zoom, Escape to close. Each image change announces its position, alt text and caption; focus returns to the thumbnail on close.

Import

import { Lightbox } from '@marbleui/ui'

Props

Prop	Type	Default
images *required	`LightboxImage[]`	`—`
className	`string`	`—`
columns	`number`	`3`

Accessibility

Keyboard interaction, focus management and ARIA semantics come from the underlying primitives: React Aria Button · React Aria Dialog · React Aria Modal · React Aria ModalOverlay. Follow the primitive's docs for the full keyboard map.

Usage notes

Thumbnail grid that opens a full-screen image viewer. For a scrolling row of slides use Carousel; for a single image use Image.

<Lightbox
  columns={4}
  images={[
    { src: '/photos/kitchen.jpg', alt: 'Renovated kitchen with oak cabinets', caption: 'Kitchen, after' },
    { src: '/photos/living-room.jpg', alt: 'Living room with a bay window' },
  ]}
/>

Each thumbnail is a button labelled “Open image n: {alt}”, so every image needs a real alt. Focus returns to the thumbnail when the viewer closes.
In the viewer, ←/→ or the arrow buttons move between images and wrap at the ends, Z or clicking the image toggles a fixed 1.8× zoom, and Escape closes.
Each change of image announces “Image n of N”, its alt and its caption.
The component always renders its own grid. There’s no prop to open it at an index or from your own trigger.

Example source · show

import { demoImage } from '../lib/demo-images'
import { Lightbox } from './lightbox'

const images = Array.from({ length: 6 }, (_, i) => ({ src: demoImage(i, 1200, 800), alt: `Landscape study ${i + 1}`, caption: `Landscape study ${i + 1} · gradient series` }))
export const styles = { Gallery: () => <Lightbox images={images} className="w-96" /> }

Source: packages/ui/src/lightbox/lightbox.tsx

Catalog

Category: media
Priority: Extra
Primitive: composed
React Aria: Modal
Base UI: Dialog