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.
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.
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.
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.