Skip to Content

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.

390 × 844

masonry - Let image heights flow through responsive columns.

390 × 844

justified - Pack images into a denser, varied grid.

390 × 844

bento - Give a featured image more space in a bento layout.

390 × 844

featured - Emphasize the image marked as featured.

390 × 844

carousel - Browse a keyboard-focusable horizontal image rail.

390 × 844

collage - Create a mixed-size editorial collage.

390 × 844

editorial - Use a relaxed, magazine-like composition.

390 × 844

fullscreen - Open large images in a full-screen lightbox.

390 × 844

thumbnails - Keep images compact with captions below.

390 × 844

horizontal - Scroll through a horizontal image sequence.

390 × 844

vertical - Stack images for a single-column story.

390 × 844

asymmetric - Balance large and small images asymmetrically.

390 × 844

mixed - Combine flexible image sizes in a dense grid.

390 × 844

portfolio - Present a portfolio in a responsive masonry flow.

390 × 844

API

PropTypeDescription
variantGallerySectionVariantgrid (default), masonry, justified, bento, featured, carousel, collage, editorial, fullscreen, thumbnails, horizontal, vertical, asymmetric, mixed, or portfolio.
itemsreadonly GalleryItem[]Images with stable, unique IDs and descriptive image data.
lightboxbooleanEnables the dialog lightbox. Defaults to true for fullscreen and false otherwise.
GalleryItem.imageEditorialImagesrc, alt, optional intrinsic dimensions, loading preference, and caption.
GalleryItem.captionReactNodeOptional item-level caption; takes precedence over image.caption.
GalleryItem.hrefstringOptional native image link when the lightbox is disabled. With the lightbox on, a caption links to this destination.
GalleryItem.featuredbooleanMarks an item for featured and asymmetric layouts.
Shared section propsMarketingSectionBasePropsHeader, 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.

PropRequiredDefault
variantNo"grid"
itemsYes—
lightboxNo—

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.

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.