Skip to content
TrademarkTrademark
Docs
Components

PhotoViewer

Updated: October 28, 2026
View on GitHub

PhotoViewer shows a set of photos full screen, the way a phone's photo app does. A photo grows out of the tile it opened from and shrinks back into it on close. Swipe or use the arrows to move between photos, with a little resistance at either end; swipe down to close; pinch, double-tap or double-click to zoom and drag to pan. Escape closes it and focus goes back to the tile. Under reduced motion every animation becomes a short fade.

It is a modal dialog on the same overlay core as Dialog and Drawer: the page behind it is inert and does not scroll, and Tab stays inside. Render it while it is open and unmount it in onClose. For a single image, Media enlarge is still the lighter choice; Media never loads the viewer.

Items

Each item is { src, alt }, plus an optional title shown above the counter and a caption shown after it ("3 / 12 · 2024"). Give width and height when you know them, so the photo opens at its real proportions; without them the viewer measures each photo as it loads. Images render through the Image adapter, like Media, so a Next.js app gets next/image and unoptimized skips it.

Which photo

index, defaultIndex and onIndexChange follow the usual pattern: leave index out and the viewer keeps its own, starting at defaultIndex, or control it to keep your page in step (scrolling the grid along, for example).

Pass deepLink="photo" to keep the open photo in the URL (?photo=<file name>), so a photo can be shared, and so Back closes the viewer. To open on a shared photo when the page loads, read the URL with photoViewerIndexFromUrl:

Without deepLink the viewer leaves the URL and history alone.

Closing

getOrigin(index) returns the element a photo opens from and closes into, usually its tile. Focus goes back to it on close. If the tile has scrolled off screen, the viewer fades out where it is; set scrollToOrigin to scroll the page to the tile instead, which suits a gallery page.

API reference

Type
Default
itemsrequired
The photos, in order: { src, alt, title?, caption?, width?, height? }.
PhotoViewerItem[]—
index
The photo on screen, controlled.
number—
defaultIndex
The first photo of an uncontrolled viewer.
number0
onIndexChange
Called with the photo the viewer moves to.
(index: number) => void—
onCloserequired
Called with the photo it closed on, once the closing animation has finished. Unmount the viewer here.
(index: number) => void—
getOrigin
The element photo `index` opens from and closes into. Focus returns to it.
(index: number) => HTMLElement | null—
scrollToOrigin
On close, scroll the page so the tile is in view instead of fading out.
booleanfalse
deepLink
Keep the open photo in this search parameter; Back closes the viewer.
string—
unoptimized
Skip the framework's image optimization.
boolean—
labels
The viewer's own words (dialog, close, previous, next, counter, error, retry), for a translated interface.
PhotoViewerLabels—
Edit this page on GitHub