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.
masonry - Let image content flow through masonry columns.
featured - Pair a large selected image with supporting views.
carousel - Navigate the selected image with buttons or arrow keys.
thumbnails - Select the main image with keyboard-operable tabs.
split - Place the main view beside a thumbnail rail.
editorial - Use a large image and generous supporting space.
fullscreen - Open the main image in an accessible lightbox.
stacked - Stack full-width images in a vertical sequence.
collage - Give the lead image more area in a collage.
horizontal - Scroll thumbnails horizontally beneath the main image.
vertical - Place the main image beside a vertical thumbnail rail.
API
| Prop | Type | Description |
|---|---|---|
variant | ProductGalleryVariant | Selects one of twelve compositions; defaults to grid. |
images | readonly ProductGalleryImage[] | Images with unique id, src, and required alt. |
ProductGalleryImage.caption | string | Optional visible caption and lightbox title. |
ProductGalleryImage.width / height | number | Optional intrinsic dimensions. |
ProductGalleryImage.loading | "eager" | "lazy" | Optional image loading preference; secondary images default to lazy loading. |
initialImageId | string | Optional initially selected image ID; an unknown ID throws. |
lightbox | boolean | Enables the dialog viewer; defaults to true for fullscreen. |
zoom | boolean | Adds a local zoom toggle for the selected image. |
| Shared section props | Marketing section props | Header, 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.
| Prop | Required | Default |
|---|---|---|
variant | No | "grid" |
images | Yes | — |
initialImageId | No | — |
lightbox | No | — |
zoom | No | false |
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.
Related components
ProductDetailsSection
Present structured product descriptions, imagery, specifications, selectors, features, comparison data, and caller-supplied availability.
ProductGridSection
Display structured ecommerce products with responsive layouts, localized prices, optional ratings, labels, links, and actions.