AddThisFeature

Product Image Gallery

Show a product's photos as a browsable set that zooms, swipes, and never jumps the page.

moderate Media & Video

What it adds

A gallery on the product page with a main image, thumbnails, zoom, and touch swipe, driven by an ordered set of product photos.

What your agent is told to do

5
  1. 1

    Reserve the main image's space from its stored aspect ratio before anything loads, so the page never reflows when the photo arrives. Serve a small blurred or solid placeholder in that box rather than leaving it empty.

  2. 2

    Extend the app's existing Image Lightbox for the full-screen zoomed view rather than building a second overlay. The gallery supplies the ordered image set and the current index; the lightbox handles the overlay, focus trapping, and escape.

  3. 3

    Serve appropriately sized images for the thumbnail, the main view, and the zoomed view, using the app's existing Image Compression or media pipeline. Do not scale one large original down in the browser.

  4. 4

    Store the display order and per-image alt text with the product, and require alt text at upload. If the app has AI Image Alt Text, use it to draft the text and let the merchant correct it.

  5. 5

    Do not preload every image at full resolution. Load the first image and its neighbours eagerly and the rest as they are approached, because a product with fifty photos otherwise costs several megabytes before the page is usable.

Edge cases it handles

8
  • The main image's box must be sized from its known aspect ratio before load, or the price and add-to-cart controls will jump down the page as each photo arrives and shoppers will click the wrong thing.
  • Pinch zoom on touch must scale the image without hijacking the page scroll. Consume the gesture only while zoomed past the natural size, and release it back to the page at the edges so the shopper is never trapped inside the gallery.
  • When the variant changes, the thumbnails and the main image must switch together and the selected index must reset to a valid position, rather than leaving a highlighted thumbnail that no longer matches what is shown.
  • A product with one image must show no thumbnail strip, no arrows, and no swipe affordance, and a product with fifty must give the strip its own scroll with a clear indication of position rather than growing the page.
  • Arrow keys must move between images when the gallery has focus, and every image needs alt text describing that specific photo. Repeating the product name on all fifty is the same as having none.
  • A missing or failed image must render a labelled placeholder in the reserved box and stay in the sequence, so the count and the thumbnail positions do not shift.
  • Swipe must not fire on a vertical scroll that drifts sideways. Require a dominant horizontal movement before taking over the gesture.
  • Autoplaying carousels and animated transitions must respect a reduced-motion preference and must never advance on their own while the shopper is looking at a photo.

Definition of done

9
  • The layout does not shift when any gallery image loads.
  • Thumbnails, the main image, and the zoomed view each receive an appropriately sized file.
  • The full-screen view is the app's existing lightbox, not a second overlay implementation.
  • Changing the variant updates thumbnails and main image together with a valid selected index.
  • Galleries of one image and of fifty images both render sensibly without arrows or an overgrown strip.
  • Arrow keys navigate the set and each image carries its own alt text.
  • Pinch zoom works on touch without trapping the page scroll.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.