Image Lightbox React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Image Lightbox is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import ImageLightbox from @/components/ui/image-lightbox.

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

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

• defaultOpendefault false
  boolean

  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.

• defaultIndexdefault 0
  number

  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.

• loopdefault false
  boolean

  Wraps from the last photo to the first (embla turns it off with too few photos).

• zoomdefault true
  boolean

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

• maxZoomdefault 4
  number

  The largest scale, relative to the fitted photo. A pinch past it resists and settles back.

• doubleTapZoomdefault 2.5
  number

  The scale a double tap or double click zooms to, centered on the tapped point (capped at maxZoom).

• swipeToClosedefault true
  boolean

  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.

• showThumbnailsdefault true
  boolean

  A synced strip under the photo from 640px up (phones have the counter instead).

• showCaptionsdefault true
  boolean

  Each photo's caption at the bottom, on a gradient. It also describes the dialog for screen readers.

• showCounterdefault true
  boolean

  The "3 / 8" counter at the top start, a polite live region.

• downloaddefault false
  boolean

  A download button: a link with the download attribute (downloadName per image). Cross-origin files open instead.

• sharedefault false
  boolean

  A share button that calls navigator.share with the photo's url; hidden where the browser has no share sheet.

• hideControlsDelaydefault 3000
  number

  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

FAQ

Used in

More React media components