Skip to Content

ProductGallerySection

Present structured product images in responsive ecommerce galleries with thumbnail navigation, keyboard controls, optional zoom, and a lightbox.

ProductGallerySection displays application-supplied product images and captions. It provides local image selection, optional zoom, and an accessible lightbox without fetching product data or adding a gallery dependency.

Beta API maturity: Beta.

Installation

import {
  ProductGallerySection,
  type ProductGalleryImage,
} from "@puzzle-ui/pieces";

Variant previews

Each of the twelve compositions has a separate preview. The thumbnails, carousel controls, zoom control, and fullscreen lightbox are interactive within the preview.

grid - Show every product image in an even grid.

390 × 844

masonry - Let image content flow through masonry columns.

390 × 844

featured - Pair a large selected image with supporting views.

390 × 844

carousel - Navigate the selected image with buttons or arrow keys.

390 × 844

thumbnails - Select the main image with keyboard-operable tabs.

390 × 844

split - Place the main view beside a thumbnail rail.

390 × 844

editorial - Use a large image and generous supporting space.

390 × 844

fullscreen - Open the main image in an accessible lightbox.

390 × 844

stacked - Stack full-width images in a vertical sequence.

390 × 844

collage - Give the lead image more area in a collage.

390 × 844

horizontal - Scroll thumbnails horizontally beneath the main image.

390 × 844

vertical - Place the main image beside a vertical thumbnail rail.

390 × 844

API

PropTypeDescription
variantProductGalleryVariantSelects one of twelve compositions; defaults to grid.
imagesreadonly ProductGalleryImage[]Images with unique id, src, and required alt.
ProductGalleryImage.captionstringOptional visible caption and lightbox title.
ProductGalleryImage.width / heightnumberOptional intrinsic dimensions.
ProductGalleryImage.loading"eager" | "lazy"Optional image loading preference; secondary images default to lazy loading.
initialImageIdstringOptional initially selected image ID; an unknown ID throws.
lightboxbooleanEnables the dialog viewer; defaults to true for fullscreen.
zoombooleanAdds a local zoom toggle for the selected image.
Shared section propsMarketing section propsHeader, root element, theme, native attributes, and children.

Empty image lists render no gallery. A missing or failed image source shows an image placeholder. The carousel and lightbox use bounded navigation and do not auto-advance.

Required and default values

Requiredness follows the exported TypeScript type. A dash means no component-level default is applied; variant-specific requirements are described in the API table above.

PropRequiredDefault
variantNo"grid"
imagesYes—
initialImageIdNo—
lightboxNo—
zoomNofalse

Usage

const images: ProductGalleryImage[] = [
  {
    id: "front",
    src: "/products/pour-over-front.jpg",
    alt: "Stoneware pour-over set viewed from the front",
    caption: "Chalk glaze",
  },
  {
    id: "detail",
    src: "/products/pour-over-detail.jpg",
    alt: "Close-up of the stoneware glaze",
  },
];

<ProductGallerySection
  variant="thumbnails"
  images={images}
  initialImageId="front"
  lightbox
  zoom
/>;

Accessibility

Informative images require alternative text. The thumbnails variant uses keyboard-operable UI tabs; other variants expose a labeled gallery region with Left/Right arrow navigation. Lightbox mode uses the UI Dialog primitive, an accessible title, a close button, Escape handling, and labeled previous/next controls. Zoom state is exposed with aria-pressed.

Data and business logic

Images, captions, and product information come from the caller. The component performs no product lookup, image transformation, inventory check, or purchase action.

Customization

Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.

import type { ComponentProps } from "react";
import { ProductGallerySection } from "@puzzle-ui/pieces";

type ProductGallerySectionProps = ComponentProps<typeof ProductGallerySection>;

export function CustomizedSection(props: ProductGallerySectionProps) {
  return <ProductGallerySection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}

Responsive behavior

Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.

Theme support

The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.

.brand-section {
  color: var(--puzzle-color-text);
  background: var(--puzzle-color-surface);
  border-color: var(--puzzle-color-border);
}

Composition

Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.

TypeScript example

The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:

import type { ComponentProps } from "react";
import { ProductGallerySection } from "@puzzle-ui/pieces";

type ProductGallerySectionProps = ComponentProps<typeof ProductGallerySection>;

export function SectionWrapper(props: ProductGallerySectionProps) {
  return <ProductGallerySection {...props} />;
}

Framework compatibility

The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.