# Image Lightbox

> A React image lightbox: a full-screen photo viewer that zooms from its thumbnail, with swipe, pinch zoom and swipe down to close.

- Type: React component (Media)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add image-lightbox`
- Docs: https://wingo-ui.com/components/image-lightbox

## Interaction

Tap a thumbnail and the photo grows out of it into a black full-screen viewer (the thumbnail's crop opens up into the whole image); closing flies it back into the thumbnail of the photo you are on, or fades when that thumbnail is off screen. Swipe or drag sideways to move between photos (embla's physics, one photo per swipe); on a phone pull a photo down and it shrinks while the page shows through, then let go past a quarter of the screen or flick to close, or it springs back. Pinch to zoom around your fingers (it resists past 1x and the max, then settles), double-tap or double-click to zoom to the tapped point and again to go back, drag to pan a zoomed photo with momentum and a soft edge, and use ctrl or cmd + wheel (a trackpad pinch) to zoom at the cursor while a plain wheel pans; a horizontal trackpad swipe pages. While zoomed, swipes pan instead of paging and swipe-down is off; changing photo resets the zoom. On desktop the toolbar (counter, zoom level pill that resets on click, zoom out / in, download, share, close), the side arrows, the caption and the thumbnail strip fade after the idle delay and come back on any mouse move or key; on a phone a single tap toggles them, like Photos. Keys: Left / Right previous / next, Home / End first / last, + or = zoom in, - zoom out, 0 reset, Escape resets a zoom first and closes on the second press. Focus stays trapped in the viewer and returns to the thumbnail that opened it; the counter is a polite live region and the caption describes the dialog. Images load only near the current one, show a spinner (over the thumbnail as a placeholder) until ready and an icon when broken. Under reduced motion it fades instead of flying, and double-tap zoom jumps.

## Installation

```bash
npx wingo-ui@latest add image-lightbox
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/image-lightbox` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/image-lightbox.tsx`

npm dependencies: `npm i @radix-ui/react-dialog @radix-ui/react-visually-hidden motion lucide-react`

Wingo UI dependencies (installed automatically):

- [Carousel](https://wingo-ui.com/components/carousel) ([Markdown](https://wingo-ui.com/components/carousel.md))
- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Spinner](https://wingo-ui.com/components/spinner) ([Markdown](https://wingo-ui.com/components/spinner.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))
- [useShortcut](https://wingo-ui.com/components/use-shortcut) ([Markdown](https://wingo-ui.com/components/use-shortcut.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { useState } from "react"
import { ImageLightbox, LightboxGallery, type LightboxImage } from "@/components/ui/image-lightbox"

const photos: LightboxImage[] = [
  { src: "/demo/apartment.jpg", alt: "Bright living room", caption: "Bright living room, 260 sq ft", width: 960, height: 600 },
  { src: "/demo/sofa.jpg", alt: "Velvet sofa", caption: "Velvet sofa, stays with the apartment", width: 960, height: 600 },
  { src: "/demo/laptop.jpg", alt: "Desk corner", caption: "Desk corner by the window", width: 960, height: 600 },
]

const labels = { dialog: "Photo gallery", download: "Save photo" }

// a grid of tiles; each photo zooms out of the tile you tap and back into it
export function ListingPhotos() {
  return <LightboxGallery images={photos} columns={{ base: 2, md: 3 }} download labels={labels} />
}

// one cover photo as the trigger, the index kept outside
export function CoverPhoto() {
  const [index, setIndex] = useState(0)
  return (
    <ImageLightbox
      images={photos}
      index={index}
      onIndexChange={setIndex}
      labels={labels}
      trigger={
        <button type="button" className="block overflow-hidden rounded-2xl">
          <img src={photos[index].src} alt={photos[index].alt} className="aspect-[16/10] w-full object-cover" />
        </button>
      }
    />
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `images` | `LightboxImage[]` |  | { src, alt, caption?, width?, height?, srcSet?, sizes?, thumbnail?, downloadName? }. width and height let the frame take the photo's shape before it loads (and let it fly from its thumbnail); thumbnail is the small file for the grid, the strip and the placeholder. An empty array never opens. |
| `open?` | `boolean` |  | Controlled visibility. Pair with onOpenChange. |
| `defaultOpen?` | `boolean` | `false` | Opens on mount, uncontrolled. The playground opens the gallery at the first photo. |
| `onOpenChange?` | `(open: boolean) => void` |  | Fires on open and on close (close button, Escape, swipe down). |
| `index?` | `number` |  | The photo shown, controlled; out of range values clamp. Pair with onIndexChange to sync an outside strip. |
| `defaultIndex?` | `number` | `0` | The photo shown first, uncontrolled. The playground opens there with defaultOpen. |
| `onIndexChange?` | `(index: number) => void` |  | Fires when the photo changes by swipe, arrow, key or thumbnail. |
| `loop?` | `boolean` | `false` | Wraps from the last photo to the first (embla turns it off with too few photos). |
| `zoom?` | `boolean` | `true` | Pinch, double tap / double click, ctrl or cmd + wheel (trackpad pinch), plain wheel to pan while zoomed, the +/- and 0 keys, and the zoom buttons (fine pointers). |
| `maxZoom?` | `number` | `4` | The largest scale, relative to the fitted photo. A pinch past it resists and settles back. |
| `doubleTapZoom?` | `number` | `2.5` | The scale a double tap or double click zooms to, centered on the tapped point (capped at maxZoom). |
| `swipeToClose?` | `boolean` | `true` | Touch and pen: pull the photo down (while not zoomed) to close. It shrinks toward 0.85 and the black fades as it follows the finger; past a quarter of the screen or a quick flick it closes, else it springs back. |
| `showThumbnails?` | `boolean` | `true` | A synced strip under the photo from 640px up (phones have the counter instead). |
| `showCaptions?` | `boolean` | `true` | Each photo's caption at the bottom, on a gradient. It also describes the dialog for screen readers. |
| `showCounter?` | `boolean` | `true` | The "3 / 8" counter at the top start, a polite live region. |
| `download?` | `boolean` | `false` | A download button: a link with the download attribute (downloadName per image). Cross-origin files open instead. |
| `share?` | `boolean` | `false` | A share button that calls navigator.share with the photo's url; hidden where the browser has no share sheet. |
| `hideControlsDelay?` | `number` | `3000` | Desktop: the controls and the cursor fade after this many ms without a mouse move or key (never while a control is hovered or focused). 0 keeps them. Phones ignore it: a tap toggles them. |
| `toolbar?` | `ReactNode` |  | Extra buttons at the start of the toolbar's action group, e.g. "Set as cover". Style them white: variant="ghost" with text-white hover:bg-white/10. |
| `trigger?` | `ReactNode` |  | An element that opens the viewer at the current index (a Radix Dialog.Trigger with asChild); the photo zooms out of it. |
| `getOrigin?` | `(index: number) => (Element \| null \| undefined)` |  | The element each photo flies out of and back into, usually its thumbnail (its first img gives the shape, its border radius the corners). Without one, or when it is off screen, the viewer fades and grows like a dialog. LightboxGallery wires it up. |
| `container?` | `HTMLElement \| null` |  | Portal target; document.body by default. |
| `labels?` | `Partial<ImageLightboxLabels>` |  | Every string: dialog ("Image viewer", the hidden title), close, previous, next, zoomIn, zoomOut, resetZoom, download, share, counter(i, n) ("3 / 8"), loading, error, slide(i, n) ("3 of 8"), goTo(i), and for the gallery openImage(i, n, alt) and moreImages(n). English by default, DEFAULT_IMAGE_LIGHTBOX_LABELS. |
| `classNames?` | `Partial<Record<"overlay" \| "content" \| "toolbar" \| "counter" \| "button" \| "stage" \| "slide" \| "zoom" \| "image" \| "spinner" \| "error" \| "footer" \| "caption" \| "thumbnails" \| "thumbnail" \| "previous" \| "next", string>>` |  | Extra classes for the inner parts. |
| `className?` | `string` |  | Classes for the full-screen content. It carries the dark class on purpose: a photo viewer is black with white controls in both themes, like iOS Photos. |

## Parts

### LightboxGallery (component)

A grid of thumbnail buttons that opens the viewer and zooms out of the tapped tile. Defaults: columns { base: 2, sm: 3, md: 4 }, gap "md" (8px), aspect "square", radius "md" (12px; sm 8px, lg and full 16px), maxVisible 0 (all; otherwise the last tile says "+N"), featured false (the first tile spans 2 x 2). Broken thumbnails show an icon. With children it renders them instead of the grid, for custom triggers with useLightbox. Takes every ImageLightbox prop. Props: ImageLightboxProps & { columns?: number | { base?, sm?, md?, lg? }; gap?: "none" | "sm" | "md" | "lg"; aspect?: "square" | "4/3" | "16/10" | "auto"; radius?: "none" | "sm" | "md" | "lg" | "full"; maxVisible?: number; featured?: boolean; renderThumbnail?: (image, index, { hiddenCount }) => ReactNode; children?: ReactNode }.

### useLightbox (hook)

Custom triggers inside a LightboxGallery: open(2, event.currentTarget) zooms photo 3 out of the pressed element and returns focus to it. Signature: () => { open(index: number, origin?: Element | null): void; close(): void; index: number; isOpen: boolean }.

### DEFAULT_IMAGE_LIGHTBOX_LABELS (constant)

The English strings, to spread and override. Type: ImageLightboxLabels.

### LightboxImage (type)

One image: { src, alt, caption?, width?, height?, srcSet?, sizes?, thumbnail?, downloadName? }.

### UseLightboxReturn (type)

What useLightbox returns: { open(index, origin?), close(), index, isOpen }.

## Examples

- **Listing hero grid**: featured puts the first photo at 2 x 2; maxVisible={5} turns the last tile into +3.
- **Single hero image**: A custom trigger with useLightbox: open(0, event.currentTarget) zooms the viewer out of the hero.
- **Download, share and a custom action**: download with downloadName per photo, share where the browser has a share sheet, and a toolbar star.
- **Loop with controls always shown**: loop wraps from the last photo to the first; hideControlsDelay={0} keeps the toolbar on desktop.
- **Chat attachments**: Three photos in a message bubble open the viewer; the thumbnail strip is off.
- **Broken image**: A missing file shows an icon in the grid and in the viewer, and never blocks swiping.
- **Controlled index**: index and onIndexChange sync an outside strip; the big preview is the trigger and the origin.

## See also

- [Carousel](https://wingo-ui.com/components/carousel) ([Markdown](https://wingo-ui.com/components/carousel.md))
- [Product gallery](https://wingo-ui.com/components/product-gallery) ([Markdown](https://wingo-ui.com/components/product-gallery.md))
- [Dialog](https://wingo-ui.com/components/dialog) ([Markdown](https://wingo-ui.com/components/dialog.md))
- [File List](https://wingo-ui.com/components/file-list) ([Markdown](https://wingo-ui.com/components/file-list.md))
- [Card](https://wingo-ui.com/components/card) ([Markdown](https://wingo-ui.com/components/card.md))

---

Canonical: https://wingo-ui.com/components/image-lightbox
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt