Photo Grid

Arrange photography in a responsive grid with captions, column spans, and image treatments.

import photo from "../assets/photography/photo-01.jpg";

<PhotoGrid
  images={[{ src: photo, caption: "The original composition" }, photo]}
/>

Usage

Import image files so Astro can optimize them and generate responsive sources. The path below assumes a page at the content root; use your own asset and adjust the path for nested or localized content.

import photo from "../assets/photography/photo-01.jpg";

<PhotoGrid images={[{ src: photo, caption: "The studio in morning light" }]} />

Use a bare imported image when it is decorative. Add a caption when the image needs a visible description and alt text.

Examples

The first preview uses the default treatment="none", with one captioned image object and one bare decorative image. Compare it with the treatments below.

Apply a monochrome treatment

Use mono to remove color across the entire set. This example also changes the tile ratio and uses two columns.

import photo from "../assets/photography/photo-01.jpg";

<PhotoGrid
  images={[
    { src: photo, caption: "The original composition" },
    { src: photo, caption: "A second application of the image treatment" },
  ]}
  cols={2}
  ratio="3 / 2"
  treatment="mono"
/>

Feature an image with a brand tint

Use span: 2 to give the first image a full row in a two-column grid. The duotone treatment uses the configured primary color.

import photo from "../assets/photography/photo-01.jpg";

<PhotoGrid
  images={[
    { src: photo, caption: "A full-width composition", span: 2 },
    { src: photo, caption: "A supporting detail" },
    { src: photo, caption: "Another supporting detail" },
  ]}
  cols={2}
  ratio="3 / 2"
  treatment="duotone"
/>

Images and responsive spans

Each caption also supplies the image’s alt text. Without a caption, the image is treated as decorative. The component accepts imported image metadata, not plain URL strings. Images crop to the chosen ratio.

Below 48rem, the grid uses two columns regardless of cols. Keep spans at 1 or 2, and no greater than your desktop column count, so an item does not create extra grid columns. A span changes the tile’s width; ratio still determines that tile’s width-to-height proportion.

API reference