GallerySection
Arrange responsive editorial images with captions, native links, masonry layouts, and an accessible keyboard-operable lightbox.
GallerySection displays application-provided images in responsive gallery compositions. It supports image dimensions, captions, optional destinations, and an optional modal lightbox with keyboard navigation.
Beta API maturity: Beta.
Installation
import {
GallerySection,
type GalleryItem,
type GallerySectionVariant,
} from "@puzzle-ui/pieces";Variant previews
Each of the fifteen variants has its own interactive preview. Lightboxes are enabled so image navigation can be tried directly.
grid - Show a balanced set of images in a responsive grid.
masonry - Let image heights flow through responsive columns.
justified - Pack images into a denser, varied grid.
bento - Give a featured image more space in a bento layout.
featured - Emphasize the image marked as featured.
carousel - Browse a keyboard-focusable horizontal image rail.
collage - Create a mixed-size editorial collage.
editorial - Use a relaxed, magazine-like composition.
fullscreen - Open large images in a full-screen lightbox.
thumbnails - Keep images compact with captions below.
horizontal - Scroll through a horizontal image sequence.
vertical - Stack images for a single-column story.
asymmetric - Balance large and small images asymmetrically.
mixed - Combine flexible image sizes in a dense grid.
portfolio - Present a portfolio in a responsive masonry flow.
API
| Prop | Type | Description |
|---|---|---|
variant | GallerySectionVariant | grid (default), masonry, justified, bento, featured, carousel, collage, editorial, fullscreen, thumbnails, horizontal, vertical, asymmetric, mixed, or portfolio. |
items | readonly GalleryItem[] | Images with stable, unique IDs and descriptive image data. |
lightbox | boolean | Enables the dialog lightbox. Defaults to true for fullscreen and false otherwise. |
GalleryItem.image | EditorialImage | src, alt, optional intrinsic dimensions, loading preference, and caption. |
GalleryItem.caption | ReactNode | Optional item-level caption; takes precedence over image.caption. |
GalleryItem.href | string | Optional native image link when the lightbox is disabled. With the lightbox on, a caption links to this destination. |
GalleryItem.featured | boolean | Marks an item for featured and asymmetric layouts. |
| Shared section props | MarketingSectionBaseProps | Header, root element, section attributes, actions, and children. |
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" |
items | Yes | — |
lightbox | No | — |
Usage
const images: GalleryItem[] = [
{
id: "studio",
image: {
src: "/journal/studio.jpg",
alt: "A bright studio with a shared worktable",
width: 1200,
height: 800,
},
caption: "The studio, just after opening",
href: "/journal/our-studio",
featured: true,
},
];
<GallerySection
variant="masonry"
title="Scenes from the studio"
items={images}
lightbox
/>;Image dimensions reserve the intended aspect ratio before loading. Images are lazy-loaded by default; the first item is eager-loaded. Missing sources render an accessible placeholder. Masonry and portfolio variants use responsive CSS columns; horizontal layouts remain scrollable at narrow widths.
Lightbox interaction
The lightbox uses the UI package's modal Dialog. The close control and native Escape behavior dismiss it; the Previous/Next buttons and Left/Right Arrow keys move between images without wrapping past the ends. Focus is managed by the dialog primitive. When lightbox mode is off, optional destinations are ordinary links.
Accessibility and rendering
The gallery is a semantic list of figures with optional <figcaption> content. Every image requires alt text; use an empty string when the image is decorative. Lightbox triggers have names derived from that alternative text. The gallery is server-renderable while the dialog is closed and does not fetch image data itself.
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 { GallerySection } from "@puzzle-ui/pieces";
type GallerySectionProps = ComponentProps<typeof GallerySection>;
export function CustomizedSection(props: GallerySectionProps) {
return <GallerySection {...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 { GallerySection } from "@puzzle-ui/pieces";
type GallerySectionProps = ComponentProps<typeof GallerySection>;
export function SectionWrapper(props: GallerySectionProps) {
return <GallerySection {...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.