Skip to Content

React Image Collage with ImageBox

Create responsive React photo collages with ImageBox. Explore image-count layouts for property listings, product photos, and portfolio previews.

Stable API maturity: Stable. API stability is stable; the documented public API is covered by component and browser tests and is intended to remain backward-compatible within a major version. This is an API commitment, not a guarantee of production readiness in every application.

ImageBox creates a responsive React image collage and chooses its layout from the number of images, including a balanced half-width split for five or more photos. Use it for a property listing, product detail, or portfolio preview. Use Image for a single image with loading controls, or a dedicated image gallery when visitors need browsing controls such as a carousel, thumbnails, or zoom.

Import

import { ImageBox, type ImageBoxImage } from "@puzzle-ui/ui";

Basic usage

Provide an image source and meaningful alternative text for each photo. The main image is loaded eagerly; supporting images are lazy-loaded.

const photos: ImageBoxImage[] = [
  {
    src: "/stay/living-room.jpg",
    alt: "Living room with a view of the garden",
  },
  { src: "/stay/bedroom.jpg", alt: "Bedroom with a king-size bed" },
  { src: "/stay/kitchen.jpg", alt: "Kitchen with a marble island" },
  { src: "/stay/bathroom.jpg", alt: "Bathroom with a walk-in shower" },
  { src: "/stay/terrace.jpg", alt: "Private terrace with outdoor seating" },
  { src: "/stay/dining-room.jpg", alt: "Dining table beside a large window" },
  { src: "/stay/reading-nook.jpg", alt: "Reading chair beside a floor lamp" },
  { src: "/stay/garden.jpg", alt: "Garden surrounding the accommodation" },
  { src: "/stay/pool.jpg", alt: "Swimming pool with sun loungers" },
  { src: "/stay/exterior.jpg", alt: "Exterior of the accommodation at sunset" },
];

<ImageBox images={photos} />;

The sample collection below is used for the live layout previews.

Automatic layouts

ImageBox uses the whole collection to select a layout and never renders more than five image elements.

One image

The single image fills the available box.

390 × 844

Two images

Two images use equal-width columns.

390 × 844

Three images

The first image occupies two-thirds of the content width. Two supporting images stack in one column.

390 × 844

Four images

Three supporting images divide the main image's height into equal rows.

390 × 844

Five images

The main image and supporting grid each take half of the content width, excluding the gap. Four supporting images form a two-by-two grid beside the main image.

390 × 844

Six images

The fifth visible image stays in the collage and carries the +1 overflow indicator.

390 × 844

Ten images

Only the first five photos are rendered; the remaining five are summarized on the fifth image.

390 × 844

Large collection

Collections of any size retain the same five-image layout. For example, 25 images show +20.

390 × 844

Geometry and spacing

For three or four images, the main image takes two-thirds of the content width and the supporting column takes one-third, excluding the gap. For five or more images, the main and supporting columns each take half of the content width, excluding the gap. In every collage layout, both columns share one fixed-height grid row. Supporting tracks use equal fractional rows (or a two-by-two grid), so their combined height including gaps exactly matches the main image.

The single gap value applies in both directions. The default uses the Puzzle spacing token and is slightly reduced at tablet widths. aspectRatio controls the collage's width-to-height ratio; every image uses object-fit: cover to fill its cell without changing the grid geometry.

390 × 844

Overflow and view-all action

The fifth photo remains visible under the overlay. The visible counter reports the number of additional photos (total - 5). Add onViewAll to make the overlay a native button and open your own gallery. On mobile, a compact count button appears on the main photo for collections of three or more.

390 × 844

Responsive behavior

At desktop (1024px and wider) and tablet (640–1023px), the collage layout stays intact. Below 640px, collections of three or more show the main image across the full width and expose the total count. Supply onViewAll to make that count an action to the complete gallery; one- and two-image layouts remain unchanged.

1024 × 844
768 × 844
390 × 844

Interactions

When onImageClick is provided, each visible photo is a native button. The callback receives the original image object and its zero-based index. onViewAll is called only by the view-all overlay; it does not trigger onImageClick. Without callbacks, photos and counters do not pretend to be interactive.

<ImageBox
  images={photos}
  onImageClick={(image, index) => openGalleryAt(index, image)}
  onViewAll={() => openGallery(0)}
/>
390 × 844

Advanced examples

Accommodation

<ImageBox
  images={stay.photos}
  aspectRatio={2}
  onViewAll={() => setGalleryOpen(true)}
/>
390 × 844

Product detail

<ImageBox
  images={product.photos}
  aspectRatio={1.8}
  gap="var(--puzzle-space-2)"
  onImageClick={(image, index) => selectProductImage(index, image)}
/>
390 × 844

Portfolio

<ImageBox images={project.images} radius="var(--puzzle-radius-xl)" />
390 × 844

Custom ratio and spacing

<ImageBox images={article.photos} aspectRatio={1.5} gap={12} radius={16} />
390 × 844
<ImageBox
  images={portfolio.photos}
  onImageClick={(image, index) => openLightbox({ image, index })}
  onViewAll={() => openLightbox({ image: portfolio.photos[0], index: 0 })}
/>
1024 × 844

API reference

ImageBoxImage

PropertyTypeRequiredDescription
srcstringYesImage URL. An empty value renders the image fallback.
altstringYesAlternative text describing the image; use an empty string only for decorative imagery.
titlestringNoOptional native image title.

ImageBoxProps

PropertyTypeDefaultRequiredDescription
imagesImageBoxImage[]—YesImages to arrange. Empty arrays render nothing; only five images are rendered at most.
aspectRationumber2NoPositive width-to-height ratio of the collage.
gapnumber | stringPuzzle spacing tokenNoShared horizontal and vertical gap. Numbers are interpreted as CSS pixels; strings may be CSS lengths or tokens.
radiusnumber | stringLarge radius tokenNoOuter corner radius. Numbers are interpreted as CSS pixels.
classNamestring—NoClass added to the collage container.
onImageClick(image: ImageBoxImage, index: number) => void—NoMakes each visible image a button and receives that image and its zero-based index.
onViewAll() => void—NoMakes the overflow/mobile count overlay a button that opens the complete collection.

Accessibility

Write meaningful alt text for every image. The collage is exposed as a labeled group announcing the collection's total photo count. Interactive photos and view-all controls use native buttons, so Tab, Enter, and Space work without custom keyboard handlers; visible focus styling follows Puzzle's focus-ring token. The view-all name includes the total number of photos. On mobile, the count control is sized for touch. The component also supports forced-colors mode and avoids non-essential animation.

Theming and styling

ImageBox uses Puzzle spacing, radius, typography, surface, and focus-ring tokens and follows the active light or dark theme. Use gap, radius, and aspectRatio for the supported layout controls, or add className to customize the outer wrapper. The underlying Image component handles image loading and presents a neutral fallback for unavailable sources. Set a theme or scoped theme around ImageBox as usual; it does not introduce its own theme configuration.