Xzero UI
Pro library
Special componentsProduct gallery

Product galleryPro

A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos.

$ pnpm dlx shadcn@4.23.0 add @xzero-ui-pro/product-gallery
Live · keyboard ready

When to use

When not to use

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/product-gallery

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 { useState } from "react";
import { ProductGallery } from "@/components/xzero/product-gallery/product-gallery";
import Button from "@/components/xzero/button/button";

export function ProductPage() {
  const [size, setSize] = useState<string | null>(null);
  return (
    <ProductGallery
      label="Field jacket"
      colors={[
        { value: "olive", label: "Olive", swatch: "#6b6a4a", images: [{ src: "/jacket/olive-1.jpg", alt: "Olive jacket, front" }, { src: "/jacket/olive-2.jpg", alt: "Olive jacket, back" }] },
        { value: "navy", label: "Navy", swatch: "#27304a", images: [{ src: "/jacket/navy-1.jpg", alt: "Navy jacket, front" }] },
      ]}
      sizes={[
        { value: "s", label: "S" },
        { value: "m", label: "M", soldOut: ["navy"] },
        { value: "l", label: "L" },
      ]}
      size={size}
      onSizeChange={setSize}
      header={<><h1>Field jacket</h1><p>$240</p></>}
      footer={<Button disabled={!size}>Add to bag</Button>}
    />
  );
}

API reference

ProductGallery

A product media gallery with a hover magnifier, a thumbnail rail, swipe on touch, a fullscreen zoom viewer, and a color and size picker.

PropTypeDefaultDescription
colors (required)ProductGalleryColor[]–Colors: { value, label, swatch, images, soldOut? }. Each carries its own images: { src, alt, srcSet? }.
sizesProductGallerySize[]–Sizes: { value, label, soldOut? }. soldOut is true for every color or a list of color values.
colorstring–Controlled color value.
defaultColorstring–Starting color when uncontrolled. Defaults to the first color.
onColorChange(color: string) => void–Called when a swatch is chosen.
sizestring | null–Controlled size value, or null for none.
defaultSizestring | nullnullStarting size when uncontrolled.
onSizeChange(size: string | null) => void–Called when a size is chosen or cleared, including when a color change sells it out.
indexnumber–Controlled index of the photo on show.
defaultIndexnumber0Starting photo when uncontrolled.
onIndexChange(index: number) => void–Called when the photo changes.
zoomnumber2.4Magnification of the hover lens and the fullscreen zoom.
magnifierbooleantrueTurns the hover lens on or off.
aspectRationumber4 / 5Aspect ratio of the main photo and thumbnails, as width / height.
labelstring"Product photos"Product name, used to name the gallery and its viewer.
headerReactNode–Content above the picker, such as the name and price.
footerReactNode–Content under the picker, such as add to bag.
classNamestring–Class on the root.
refRef<HTMLDivElement>–The root element.

isSoldOut

Whether a size is sold out in a given color.

PropTypeDefaultDescription
size (required)ProductGallerySize–The size entry.
color (required)string–The color value.

Keyboard interactions

KeysAction
ArrowLeft / ArrowRightSteps photos on the main photo, the thumbnail rail, and in the viewer.
Arrow keys / Home / EndMove and select within the thumbnail rail, swatches, and sizes; sold-out sizes are skipped.
Enter / SpaceOpens the fullscreen viewer from the main photo.
EscapeZooms out in the viewer, then closes it and returns focus to the photo.
TabCycles within the viewer's buttons while it is open.

Accessibility

Motion

Responsive behavior

Performance

Notes for AI

Also in galleries

Guidance for AI tools

Product gallery: A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos. 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

Browse all components