Product gallery 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

Product gallery 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 ProductGallery from @/components/ui/product-gallery.

import { ProductGallery, type ProductGalleryImage } from "@/components/ui/product-gallery"
import { FavoriteButton } from "@/components/ui/favorite-button"
import { Badge } from "@/components/ui/badge"
import { Sparkles } from "lucide-react"

const images: ProductGalleryImage[] = [
  { src: "/demo/apartment.jpg", width: 960, height: 600, alt: "Bright living room", caption: "Bright living room, 24 m²" },
  { src: "/demo/sofa.jpg", width: 960, height: 600, alt: "Green velvet sofa", caption: "The lounge corner" },
  { src: "/demo/city.jpg", width: 960, height: 600, alt: "View over the boulevard", caption: "View from the balcony" },
]

export function ListingPhotos() {
  return (
    <ProductGallery
      images={images}
      bleedOnMobile
      badges={<Badge variant="soft" tone="warning" leftIcon={<Sparkles />}>Promovat</Badge>}
      actions={<FavoriteButton variant="overlay" />}
      labels={{ gallery: "Listing photos", open: "Open full screen", noImage: "No photos yet" }}
    />
  )
}

Props

• images*
  ProductGalleryImage[]

  The photos: { src, alt, caption?, width?, height?, srcSet?, sizes?, thumbnail? } (LightboxImage plus a thumbnail file). width and height let the viewer take its final shape before the file loads; captions show in the viewer.

• defaultIndexdefault 0
  number

  The photo on the stage at first. Out of range values clamp to the first or last photo.

• index
  number

  Controlled photo index. The stage, the thumbnails and the viewer all follow it.

• onIndexChange
  (index: number) => void

  Called when a swipe, an arrow, a key, a thumbnail or the viewer changes the photo.

• defaultOpendefault false
  boolean

  Starts with the full-screen viewer open at the current photo.

• open
  boolean

  Controlled viewer state.

• onOpenChange
  (open: boolean) => void

  Called when the viewer opens (a click, a tap, Enter, the expand button, +N) or closes.

• thumbnailsdefault "start"
  "start" | "bottom" | "none"

  start: a vertical rail beside the stage, exactly as tall as it (it scrolls when the photos do not fit), once the gallery is at least 512px wide (a container query); in a narrower column a mouse gets it as a strip under the stage. bottom: a strip under the stage. On touch screens below 512px the indicator replaces both.

• aspectdefault "4/3"
  "1/1" | "4/3" | "3/4" | "16/10"

  The stage's shape. Photos are cropped (cover) or letterboxed (contain) into it.

• fitdefault "cover"
  "cover" | "contain"

  cover fills the stage and crops; contain shows the whole photo on white in light mode and on the tinted stage in dark mode, for product shots.

• zoomdefault "hover"
  "hover" | "lens" | "none"

  Mouse pointers only. hover scales the photo in place and pans with the cursor; lens shows a round magnifier. The zoom never goes past twice a photo's natural width, and touch screens use the viewer's pinch instead.

• zoomScaledefault 2
  number

  How far the hover zoom or the lens magnifies.

• lightboxdefault true
  boolean

  A click, a tap or Enter opens the full-screen ImageLightbox at that photo, growing out of the stage. Off: no viewer, no expand button.

• indicatordefault "counter"
  "counter" | "dots" | "none"

  The position cue where thumbnails do not show (touch screens below 512px of gallery width, or thumbnails="none"): a "3 / 12" chip at the bottom end or dots at the bottom center.

• showArrowsdefault true
  boolean

  Previous / next buttons over the stage for mouse and trackpad users, shown on hover or keyboard focus; touch screens swipe instead.

• loopdefault false
  boolean

  Wraps from the last photo to the first, on the stage and in the viewer.

• maxThumbnailsdefault 6
  number

  How many thumbnails show. When there are more photos the last visible one reads "+N" and opens the viewer at that photo.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg"

  The stage's corners: 0 / 12 / 16 / 24px. Thumbnails follow one step smaller.

• bleedOnMobiledefault false
  boolean

  Below 768px the stage drops its corners, for detail pages that run the gallery edge to edge.

• badges
  ReactNode

  Top start, over the photo: a "Promovat" badge, the condition.

• actions
  ReactNode

  Top end, over the photo: e.g. <FavoriteButton variant="overlay" /> and a share button (keep them 44px on touch).

• lightboxProps
  Partial<ImageLightboxProps>

  Anything else for the viewer (labels, download, share, showThumbnails, maxZoom...). images, open and index belong to the gallery.

• labels
  Partial<ProductGalleryLabels>

  gallery "Photos", thumbnails "Photo thumbnails", open "Open full screen", thumbnail (i, n) => "Show photo i of n", more (n) => "+n", counter (i, n) => "i / n", zoomHint "Hover to zoom, click to open", noImage "No photos", previous "Previous photo", next "Next photo", slide (i, n) => "i of n".

• classNames
  Partial<Record<"thumbnails" | "thumbnail" | "stage" | "slide" | "image" | "lens" | "counter" | "dots" | "hint" | "expand" | "badges" | "actions", string>>

  Extra classes for the inner parts.

Parts

FAQ

Used in

More React commerce components