Photo gridPro

• Type: Component (special)
• Access: Xzero Pro
• Page: https://ui.xzero.co.uk/components/photo-grid
• Markdown: https://ui.xzero.co.uk/components/photo-grid/markdown
• Source file: registry/components/photo-grid/photo-grid.tsx
• Dependencies: motion, lucide-react
• Keywords: special, photos, gallery, react photo grid, photo library, pinch to zoom grid, ios photos grid, image gallery with viewer, album grid, photo viewer

When to use

• A browsable photo library or album where people zoom between column counts.
• Galleries that need favorites and a full-screen viewer with a filmstrip.
• Touch and trackpad users who expect pinch to change density.

When not to use

• Use lightbox-gallery for a masonry layout that keeps each photo's aspect ratio.
• Use carousel for a short inline slideshow.
• Use image-compare for before and after pairs.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui-pro/photo-grid

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { PhotoGrid, type GridPhoto } from "@/components/xzero/photo-grid/photo-grid";

export function Album({ photos }: { photos: GridPhoto[] }) {
  return (
    <PhotoGrid
      title="September"
      photos={photos}
      defaultColumns={4}
      onFavoriteChange={(id, favorite) => saveFavorite(id, favorite)}
    />
  );
}

API reference

PhotoGrid

A photo library grid with pinch or button zoom between column counts, favorites, and a full-screen viewer that grows from the tapped cell.

Prop	Type	Default	Description
photos (required)	{ id: string; src: string; srcSet?: string; alt: string; width: number; height: number; title: string; detail?: string }[]	–	Photos in order. width and height are the intrinsic size; detail is a short line in the viewer, such as the date.
title (required)	string	–	Names the library, such as a month or album.
zoomLevels	number[]	[5, 3, 2]	Column counts the zoom steps between.
defaultColumns	number	3	Initial column count.
onColumnsChange	(columns: number) => void	–	Called when the zoom level changes.
defaultFavorites	string[]	–	Ids favorited at mount.
onFavoriteChange	(id: string, favorite: boolean) => void	–	Called when a photo is favorited or unfavorited.
onViewerChange	(id: string | null) => void	–	Called with the photo id when the viewer opens and null as it starts to close.
className	string	–	Extra class on the root.

Keyboard interactions

Keys	Action
Arrow keys	Move focus between photos in the grid.
PageUp / PageDown / Home / End	Jump by three rows or to the first or last photo.
+ / -	Zoom in or out a level around the focused photo.
Enter / Space	Opens the focused photo in the viewer.
ArrowLeft / ArrowRight / Home / End	In the viewer, change photo.
Escape	Closes the viewer.

Accessibility

• The grid is a labelled list of buttons named by each photo's alt text, with ", favorite" appended when favorited.
• Zoom buttons use aria-pressed; the viewer is a labelled dialog and its filmstrip is a slider with the photo title in aria-valuetext.
• Viewer changes are announced in a polite status region.

Motion

• Pinch zoom scales live and reflows around the photo under the fingers; the viewer grows from the tapped cell and can be dragged down to dismiss.
• Counters and favorite icons roll or pop in with a short blur.
• Reduced motion removes layout travel and keeps fades.

Responsive behavior

• Columns come from zoomLevels, not breakpoints; the root is a container and needs a height, with a 320px minimum.
• Below 480px the header and filmstrip shrink, previous and next buttons hide, and swipe or the filmstrip pages instead.
• Previous and next arrows are hidden on hover-less devices, where swipe is the main gesture.

Performance

• The grid is not virtualized; every photo renders a thumbnail, so paginate very large libraries.
• The viewer only mounts photos near the current one, and passing srcSet keeps thumbnails light.
• The header and viewer use backdrop blur, which drops to solid surfaces under prefers-reduced-transparency.

Notes for AI

• Choose it for a browsable photo library or album. Use carousel for a short slideshow and image-compare for before/after.
• Always pass width and height so the viewer and filmstrip can fit each photo without layout shift; pass srcSet for sharp thumbnails.

Related

• Carousel: Browse a row of slides by dragging, flicking, or arrowing through them.
• Image compare: Drag a divider across two images to see what changed.
• Cover flow: A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.
• Dialog: A focused surface for decisions that need attention.

Also in galleries

• Product gallery: A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos.
• Lightbox gallery: A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.

Guidance for AI tools

Photo grid: Pinch through zoom levels and open any photo straight from its cell. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt