Lightbox Gallery (React)

A thumbnail wall (CSS grid, gentle hover zoom, fixed 4:3 cells) — click any tile to open a full-screen lightbox: the large image scales up from the thumbnail's position as a shared element and shrinks back into place on close. Inside the lightbox the full gesture set is implemented with pointer events — mouse wheel or two-finger pinch zooms around the cursor / pinch midpoint, a single-finger drag pans once zoomed in (clamped to the image bounds), a horizontal swipe past 80px switches images at 1×, and a double-tap toggles between 1× and 2×. The toolbar carries the counter, zoom in/out, and close; arrow buttons and the ←/→ keys change images; a caption bar and a clickable thumbnail strip sit at the bottom. Opening locks page scroll, moves focus to the close button and cycles it inside the lightbox; closing returns focus to the original thumbnail.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

<LightboxGallery />

Installation

Usage

import { LightboxGallery, type LightboxImage } from "@/components/ui/lightbox-gallery";

const images: LightboxImage[] = [
  { id: "a", src: "/photos/a.jpg", thumb: "/photos/a-thumb.jpg", alt: "Sunrise at the shore", caption: "The east coast at 5 a.m." },
  { id: "b", src: "/photos/b.jpg", alt: "Sea of clouds in the valley" },
  { id: "c", src: "/photos/c.jpg", alt: "Old street in the afternoon", caption: "Light and shadow under the eaves" },
];

// Uncontrolled: click a thumbnail to open; the component manages open state and index
<LightboxGallery images={images} columns={3} loop />

// Controlled: open to a specific image from an external button
const [open, setOpen] = useState(false);
const [index, setIndex] = useState(0);
<LightboxGallery
  images={images}
  open={open}
  onOpenChange={setOpen}
  index={index}
  onIndexChange={setIndex}
  showThumbnails={false}
  zoomMax={6}
/>

Props

LightboxImage

LightboxGalleryLabels

The LightboxImage, LightboxGalleryLabels, and LightboxGalleryProps types are also named exports.

How it works

• Shared-element entrance: the image the lightbox opens with shares a Motion layoutId with its thumbnail, so it scales up from the thumbnail's position; if you close while still on that image it shrinks back into the thumbnail, and after navigating to another image it fades out instead. Images navigated to afterwards slide in and out horizontally, and zoom/pan reset on every switch.
• Gestures: implemented with pointer events, so mouse, touch, and pen behave the same. The wheel (including trackpad pinch, which arrives as a wheel event with ctrlKey) zooms around the cursor; a two-finger pinch tracks the distance and midpoint of two pointers, so you can pan while pinching; above 1× a single-finger drag pans, clamped to the image bounds; at 1× a horizontal displacement past 80px switches images (with resistance and a spring back at the ends when loop is off); a second tap within 300ms and 24px counts as a double-tap and toggles between 1× and 2×; tapping the backdrop outside the image closes.
• Keyboard: ←/→ to navigate, Home/End to jump to the ends, Esc to close, +/- to zoom, 0 to reset to 1×.
• Sizing: the large image is fitted inside the stage with max-width: 100%; max-height: 100%, so images smaller than the stage are not upscaled; src needs an intrinsic size (all raster formats have one; give SVGs a width/height). The previous and next images are preloaded while open.
• Portal and scroll lock: the lightbox is rendered into document.body via createPortal so ancestor transform/overflow cannot clip it; while open, an effect sets document.body.style.overflow to hidden and restores the previous value on close or unmount.

Accessibility

• The lightbox is role="dialog" with aria-modal="true"; its aria-label comes from labels.dialog, and when a caption exists aria-describedby points at the caption bar. Focus moves to the close button on open, Tab/Shift+Tab cycle inside the lightbox, and focus returns to the clicked thumbnail on close
• Every wall cell is a button (aria-haspopup="dialog") whose accessible name is "alt text (View larger)"; toolbar, arrow, and strip buttons all carry aria-label, the current thumbnail is marked with aria-current, and an aria-live="polite" region announces "image n of N: alt text" on navigation
• Every interaction has a keyboard equivalent (arrow keys to navigate, Esc to close, +/-/0 to zoom), and buttons show a focus-visible outline
• When the user has "reduce motion" enabled at the system level, the shared-element morph becomes a fade, the horizontal slide becomes a fade, zoom snaps to the target without tweening, and the thumbnail strip scrolls instantly — nothing functional is lost