Skip to content
Commerce block

Product Image Gallery

Main image with a thumbnail strip built as a real tablist, so arrow keys work and the ratio is fixed to stop the buy box shifting.

119 lineslucide-reactAdded 8 Aug 2026Updated 11 Sept 2026
  • gallery
  • images
  • product
  • thumbnails
  • tabs

What's included

  • components/product-gallery.tsx
  • Needs lucide-react

Works with

  • React
  • Next.js
  • Tailwind CSS
  • TypeScript

npx hoverlab add product-gallery

Or over MCP, from your editor's agent — no account needed.

License

Free to read, copy and install, for personal and non-commercial projects. Shipping it in client work or a paid product needs Pro ($79 once). The source lands in your repo and stops being ours — no attribution, nothing to upgrade.

Was this useful?

Start a page with this section — add more, order them, and leave with the page source.

Preview

Rendered live in your current theme — this is the same component whose source is below, not a screenshot of it.

Source

components/product-gallery.tsx
'use client'

/**
 * <ProductGallery> — main image with a thumbnail strip.
 *
 * The thumbnails are a `tablist`, and the main image is the panel. That is
 * the correct pattern: the strip selects which of several views is shown,
 * which is exactly what tabs are, and it buys arrow-key navigation that a
 * row of buttons does not have.
 *
 * `aria-live` is deliberately absent. The visible image changing is not an
 * announcement — the tab's selected state already conveys it, and adding a
 * live region here makes a screen reader say the caption twice.
 *
 * Images are gradient placeholders rather than remote URLs, so the block
 * works offline and in a sandbox. Swap for `next/image` with a fixed
 * `aspect-ratio` when you wire it up — keeping the ratio is what stops the
 * gallery shifting the buy box down the page as images load.
 */

import * as React from 'react'
import { Expand } from 'lucide-react'

export interface GalleryView {
  id: string
  /** Alt text for the main image, and the thumbnail's accessible name. */
  label: string
  swatch: string
}

export interface ProductGalleryProps {
  views?: GalleryView[]
  className?: string
}

const DEFAULT_VIEWS: GalleryView[] = [
  { id: 'front', label: 'Front view', swatch: 'from-stone-200 to-stone-400' },
  { id: 'back', label: 'Back view', swatch: 'from-stone-300 to-stone-500' },
  { id: 'detail', label: 'Fabric detail', swatch: 'from-amber-200 to-stone-400' },
  { id: 'worn', label: 'Worn on model', swatch: 'from-zinc-300 to-zinc-500' },
]

export function ProductGallery({
  views = DEFAULT_VIEWS,
  className = '',
}: ProductGalleryProps) {
  /*
     Per-instance prefix. The panel ids were literal, so two galleries
     on one document -- a product page and a related-items rail, or two
     page previews on the catalog hub -- emitted the same id twice and
     every tab's `aria-controls` resolved to the first one's panel.
     Client component, so `useId` is the right tool here.
  */
  const uid = React.useId()
  const [active, setActive] = React.useState(0)
  const view = views[active] ?? views[0]

  function onKeyDown(event: React.KeyboardEvent) {
    if (event.key === 'ArrowRight') {
      event.preventDefault()
      setActive((i) => (i + 1) % views.length)
    } else if (event.key === 'ArrowLeft') {
      event.preventDefault()
      setActive((i) => (i - 1 + views.length) % views.length)
    }
  }

  return (
    <div className={`flex flex-col gap-3 ${className}`}>
      {/* Fixed ratio — the buy box must not move as images swap. */}
      <div
        id={`${uid}-gallery-panel-${view.id}`}
        role="tabpanel"
        aria-label={view.label}
        className="group relative aspect-square overflow-hidden rounded-2xl border border-border/60 bg-muted"
      >
        <div
          aria-hidden
          className={`h-full w-full bg-gradient-to-br ${view.swatch} transition-transform duration-500 group-hover:scale-[1.03]`}
        />

        <button
          type="button"
          aria-label={`Expand ${view.label}`}
          className="absolute bottom-3 end-3 rounded-full bg-background/85 p-2.5 text-muted-foreground opacity-0 backdrop-blur transition-all hover:text-foreground focus-visible:opacity-100 group-hover:opacity-100"
        >
          <Expand aria-hidden className="h-4 w-4" />
        </button>
      </div>

      <div
        role="tablist"
        aria-label="Product images"
        onKeyDown={onKeyDown}
        className="relative flex gap-2.5 overflow-x-auto pb-1"
      >
        {views.map((v, i) => (
          <button
            key={v.id}
            type="button"
            role="tab"
            aria-selected={i === active}
            aria-controls={`${uid}-gallery-panel-${v.id}`}
            // Only the active tab is in the tab order; arrows move within.
            tabIndex={i === active ? 0 : -1}
            onClick={() => setActive(i)}
            className={`aspect-square w-16 shrink-0 overflow-hidden rounded-xl border-2 transition-colors sm:w-20 ${
              i === active ? 'border-primary' : 'border-transparent hover:border-border'
            }`}
          >
            <span className="sr-only">{v.label}</span>
            <span aria-hidden className={`block h-full w-full bg-gradient-to-br ${v.swatch}`} />
          </button>
        ))}
      </div>
    </div>
  )
}

Before you paste

  • Styling is Tailwind utility classes on semantic tokens (bg-card, text-muted-foreground) — it inherits your theme instead of overriding it.
  • Install: npm i lucide-react
  • Every prop has a default, so it renders standalone before you wire it up.

Where it goes

Drop it at components/product-gallery.tsx and import it where you need the section:

import { ProductGallery } from '@/components/product-gallery'

Props

Read out of the component’s own type and signature, so this cannot drift from the source below. Every prop has a default — the component renders standalone before you pass it anything.

PropTypeDefault
viewsGalleryView[]DEFAULT_VIEWS
classNamestring''

Not using React?

The same block rendered once to markup, wrapped as a file your framework compiles. Tailwind classes are framework-agnostic, so the design transfers intact — the behaviour does not.

This block is interactive. The markup below is its initial state with the event handlers stripped — you will need to re-wire the behaviour in your framework.

product-gallery.html
<!--
  Product Image Gallery — markup from the Hoverlab catalog.

  This is the block rendered once to HTML and wrapped as a component
  file. It is not a port of the React source: the Tailwind classes carry
  the design, which is the part that took the work, and they are the same
  in every framework.

  This block is interactive in React and the handlers are NOT here.
  Buttons, toggles and menus render in their initial state and do
  nothing until you wire them up.
-->
<div class="flex flex-col gap-3 ">
  <div id="_R_0_-gallery-panel-front" role="tabpanel" aria-label="Front view" class="group relative aspect-square overflow-hidden rounded-2xl border border-border/60 bg-muted">
    <div aria-hidden="true" class="h-full w-full bg-gradient-to-br from-stone-200 to-stone-400 transition-transform duration-500 group-hover:scale-[1.03]"></div>
    <button type="button" aria-label="Expand Front view" class="absolute bottom-3 end-3 rounded-full bg-background/85 p-2.5 text-muted-foreground opacity-0 backdrop-blur transition-all hover:text-foreground focus-visible:opacity-100 group-hover:opacity-100">
      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-expand h-4 w-4" aria-hidden="true">
        <path d="m15 15 6 6"></path>
        <path d="m15 9 6-6"></path>
        <path d="M21 16v5h-5"></path>
        <path d="M21 8V3h-5"></path>
        <path d="M3 16v5h5"></path>
        <path d="m3 21 6-6"></path>
        <path d="M3 8V3h5"></path>
        <path d="M9 9 3 3"></path>
      </svg>
    </button>
  </div>
  <div role="tablist" aria-label="Product images" class="relative flex gap-2.5 overflow-x-auto pb-1">
    <button type="button" role="tab" aria-selected="true" aria-controls="_R_0_-gallery-panel-front" tabindex="0" class="aspect-square w-16 shrink-0 overflow-hidden rounded-xl border-2 transition-colors sm:w-20 border-primary">
      <span class="sr-only">Front view</span>
      <span aria-hidden="true" class="block h-full w-full bg-gradient-to-br from-stone-200 to-stone-400"></span>
    </button>
    <button type="button" role="tab" aria-selected="false" aria-controls="_R_0_-gallery-panel-back" tabindex="-1" class="aspect-square w-16 shrink-0 overflow-hidden rounded-xl border-2 transition-colors sm:w-20 border-transparent hover:border-border">
      <span class="sr-only">Back view</span>
      <span aria-hidden="true" class="block h-full w-full bg-gradient-to-br from-stone-300 to-stone-500"></span>
    </button>
    <button type="button" role="tab" aria-selected="false" aria-controls="_R_0_-gallery-panel-detail" tabindex="-1" class="aspect-square w-16 shrink-0 overflow-hidden rounded-xl border-2 transition-colors sm:w-20 border-transparent hover:border-border">
      <span class="sr-only">Fabric detail</span>
      <span aria-hidden="true" class="block h-full w-full bg-gradient-to-br from-amber-200 to-stone-400"></span>
    </button>
    <button type="button" role="tab" aria-selected="false" aria-controls="_R_0_-gallery-panel-worn" tabindex="-1" class="aspect-square w-16 shrink-0 overflow-hidden rounded-xl border-2 transition-colors sm:w-20 border-transparent hover:border-border">
      <span class="sr-only">Worn on model</span>
      <span aria-hidden="true" class="block h-full w-full bg-gradient-to-br from-zinc-300 to-zinc-500"></span>
    </button>
  </div>
</div>
  • This is rendered HTML, not a translation of the React source. The Tailwind classes carry the design and work in any framework.
  • It is one frame: the component in its initial state, with no props applied beyond the defaults.
  • This block is interactive in React — toggles, menus or form state. None of that survives here; the markup is the closed/default state and the handlers are gone. Re-wire them in your own framework.
  • Requires Tailwind, and the design tokens the classes reference (bg-card, text-muted-foreground, and so on). The template ZIPs ship a globals.css that defines them.

What each framework gets across the whole catalog — effects convert properly; this rung is markup.

For AI

The component, its props, the design tokens it expects and the command that installs it — as one prompt. Paste it into Claude, Cursor, v0 or ChatGPT and what they build around it will match the rest of the catalog instead of inventing its own system.

See the prompt

Used in these pages

Want the whole screen instead of this one section? Open a page and copy it entire.

6 more blocks in Product Detail

All of them free to read, copy and install — no account, no locked tiles, no watermarked preview. The whole catalog is open, and so are the API and the CLI.

Browse Product Detail

Shipping one commercially

Copying the code is free. Putting it in client work or a paid product is what Pro is for — the licence, not the access.

  • A commercial licence for everything in the catalog
  • Unlimited bundle exports, in Vue, Svelte and Tailwind
  • One payment — no subscription, nothing to renew
Pro — $79 once

More Product Detail blocks

View category
Open the full page for this block

Variant & Add-to-Cart Box

Price, variant radiogroup, quantity stepper and add-to-bag — with sold-out sizes disabled and visible rather than hidden.

Product Detail347 lines1 dep
Open the full page for this block

Product Details Accordion

Description, materials, delivery and returns in named <details> elements — no JavaScript, and the copy stays indexable while collapsed.

Product Detail156 lines1 dep
Open the full page for this block

Rating Distribution Summary

Average rating with a clickable histogram — because a 4.3 of forties and fives is a different product from a 4.3 of ones and fives.

Product Detail126 lines1 dep
Open the full page for this block

Size Guide

The panel that decides whether the parcel comes back: what the model is wearing and what previous buyers did, above a table whose inches are converted rather than maintained twice.

Product Detail227 lines1 dep
Open the full page for this block

Product Spec Split

The specification table beside the product image, with the two or three figures that decide the purchase pulled out of it.

Product Detail159 linesNo deps
Open the full page for this block

Back In Stock Form

The capture that replaces a dead sold-out button, with the honest caveat that a notification is not a reservation.

Product Detail177 linesNo deps