Start typing to search components and docs…
↵ select ↑ ↓ navigate ESC close

ProductGallery

Scroll-snap based product image gallery with fullscreen dialog lightbox. Zero external dependencies — uses CSS scroll-snap, IntersectionObserver, and native <dialog>.

Import (subpath — has <script>, must NOT go in barrel):

<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="js"><code><span class="line"><span style="color:#F97583">import</span><span style="color:#E1E4E8"> ProductGallery </span><span style="color:#F97583">from</span><span style="color:#9ECBFF"> 'spoko-design-system/components/Product/ProductGallery.astro'</span></span></code></pre>

Features

  • Slider — CSS scroll-snap, swipe on mobile, mouse drag on desktop
  • Thumbnails — synced via IntersectionObserver, desktop only
  • Counter — fraction (1/5), always visible
  • Arrows — hover reveal animation, desktop only
  • Dialog — fullscreen lightbox with zoom (click/wheel/double-tap) + pan
  • Keyboard — ArrowLeft/Right in dialog, Escape to close

Basic usage

Product image 1
Product image 2
Product image 3
Product image 4
Product image 5
1/5
1/5
Product image 1
Product image 2
Product image 3
Product image 4
Product image 5
<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="astro"><code><span class="line"><span style="color:#E1E4E8">&#x3C;</span><span style="color:#79B8FF">ProductGallery</span></span> <span class="line"><span style="color:#B392F0"> images</span><span style="color:#E1E4E8">={[</span></span> <span class="line"><span style="color:#E1E4E8"> { src: </span><span style="color:#9ECBFF">"/img/product-1.avif"</span><span style="color:#E1E4E8">, thumb: </span><span style="color:#9ECBFF">"/img/product-1-thumb.avif"</span><span style="color:#E1E4E8">, full: </span><span style="color:#9ECBFF">"/img/product-1-full.jpg"</span><span style="color:#E1E4E8">, alt: </span><span style="color:#9ECBFF">"Product image 1"</span><span style="color:#E1E4E8"> },</span></span> <span class="line"><span style="color:#E1E4E8"> { src: </span><span style="color:#9ECBFF">"/img/product-2.avif"</span><span style="color:#E1E4E8">, thumb: </span><span style="color:#9ECBFF">"/img/product-2-thumb.avif"</span><span style="color:#E1E4E8">, full: </span><span style="color:#9ECBFF">"/img/product-2-full.jpg"</span><span style="color:#E1E4E8">, alt: </span><span style="color:#9ECBFF">"Product image 2"</span><span style="color:#E1E4E8"> },</span></span> <span class="line"><span style="color:#E1E4E8"> ]}</span></span> <span class="line"><span style="color:#E1E4E8">/></span></span></code></pre>

Many images (10)

Image 1
Image 2
Image 3
Image 4
Image 5
Image 6
Image 7
Image 8
Image 9
Image 10
1/10
1/10
Image 1
Image 2
Image 3
Image 4
Image 5
Image 6
Image 7
Image 8
Image 9
Image 10

With badges slot

Product with badge
Product image 2
1/2
NEW
1/2
Product with badge
Product image 2
<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="astro"><code><span class="line"><span style="color:#E1E4E8">&#x3C;</span><span style="color:#79B8FF">ProductGallery</span><span style="color:#B392F0"> images</span><span style="color:#E1E4E8">={images}></span></span> <span class="line"><span style="color:#E1E4E8"> &#x3C;</span><span style="color:#79B8FF">Badges</span><span style="color:#B392F0"> badges</span><span style="color:#E1E4E8">={product.badges} </span><span style="color:#B392F0">class</span><span style="color:#E1E4E8">=</span><span style="color:#9ECBFF">"top-2"</span><span style="color:#E1E4E8"> /></span></span> <span class="line"><span style="color:#E1E4E8">&#x3C;/</span><span style="color:#79B8FF">ProductGallery</span><span style="color:#E1E4E8">></span></span></code></pre>

Single image (no thumbnails)

Single product image
1/1
1/1
Single product image

No images (empty state)

No images available

Custom aspect ratio

Wide image 1
Wide image 2
1/2
1/2
Wide image 1
Wide image 2

Props

PropTypeDefaultDescription
imagesGalleryImage[][]Array of image objects.
aspectRatiostring'4/3'CSS `aspect-ratio` for the slider.
classstring—Additional CSS class on root element.
ariaLabelstring'Product image gallery'Accessible label for the carousel region.

GalleryImage shape

<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#F97583">interface</span><span style="color:#B392F0"> GalleryImage</span><span style="color:#E1E4E8"> {</span></span> <span class="line"><span style="color:#FFAB70"> src</span><span style="color:#F97583">:</span><span style="color:#79B8FF"> string</span><span style="color:#E1E4E8">; </span><span style="color:#6A737D">// Main image URL (used in slider) — required</span></span> <span class="line"><span style="color:#FFAB70"> thumb</span><span style="color:#F97583">?:</span><span style="color:#79B8FF"> string</span><span style="color:#E1E4E8">; </span><span style="color:#6A737D">// Thumbnail URL (falls back to `src`)</span></span> <span class="line"><span style="color:#FFAB70"> full</span><span style="color:#F97583">?:</span><span style="color:#79B8FF"> string</span><span style="color:#E1E4E8">; </span><span style="color:#6A737D">// Full-res URL for dialog lightbox (falls back to `src`)</span></span> <span class="line"><span style="color:#FFAB70"> alt</span><span style="color:#F97583">:</span><span style="color:#79B8FF"> string</span><span style="color:#E1E4E8">; </span><span style="color:#6A737D">// Alt text — required</span></span> <span class="line"><span style="color:#E1E4E8">}</span></span></code></pre>

Slots

Slot Description
default Overlay content (e.g. badges) positioned inside the main slider area
empty Custom content when images is empty

Integration examples

Multi-resolution CDN images

<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="astro"><code><span class="line"><span style="color:#E1E4E8">&#x3C;</span><span style="color:#79B8FF">ProductGallery</span></span> <span class="line"><span style="color:#B392F0"> images</span><span style="color:#E1E4E8">={product.images.</span><span style="color:#B392F0">map</span><span style="color:#E1E4E8">((</span><span style="color:#FFAB70">img</span><span style="color:#E1E4E8">, </span><span style="color:#FFAB70">i</span><span style="color:#E1E4E8">) </span><span style="color:#F97583">=></span><span style="color:#E1E4E8"> ({</span></span> <span class="line"><span style="color:#E1E4E8"> src: img.avif_1200 </span><span style="color:#F97583">||</span><span style="color:#E1E4E8"> img.webp_1200,</span></span> <span class="line"><span style="color:#E1E4E8"> thumb: img.avif_320 </span><span style="color:#F97583">||</span><span style="color:#E1E4E8"> img.avif_640,</span></span> <span class="line"><span style="color:#E1E4E8"> full: img.original </span><span style="color:#F97583">||</span><span style="color:#E1E4E8"> img.url,</span></span> <span class="line"><span style="color:#E1E4E8"> alt: </span><span style="color:#9ECBFF">`${</span><span style="color:#E1E4E8">product</span><span style="color:#9ECBFF">.</span><span style="color:#E1E4E8">number</span><span style="color:#9ECBFF">} - ${</span><span style="color:#E1E4E8">product</span><span style="color:#9ECBFF">.</span><span style="color:#E1E4E8">name</span><span style="color:#9ECBFF">} [${</span><span style="color:#E1E4E8">i</span><span style="color:#F97583"> +</span><span style="color:#79B8FF"> 1</span><span style="color:#9ECBFF">}/${</span><span style="color:#E1E4E8">product</span><span style="color:#9ECBFF">.</span><span style="color:#E1E4E8">images</span><span style="color:#9ECBFF">.</span><span style="color:#79B8FF">length</span><span style="color:#9ECBFF">}]`</span><span style="color:#E1E4E8">,</span></span> <span class="line"><span style="color:#E1E4E8"> }))}</span></span> <span class="line"><span style="color:#E1E4E8">></span></span> <span class="line"><span style="color:#E1E4E8"> &#x3C;</span><span style="color:#79B8FF">Badges</span><span style="color:#B392F0"> badges</span><span style="color:#E1E4E8">={product.badges} </span><span style="color:#B392F0">class</span><span style="color:#E1E4E8">=</span><span style="color:#9ECBFF">"top-2"</span><span style="color:#E1E4E8"> /></span></span> <span class="line"><span style="color:#E1E4E8">&#x3C;/</span><span style="color:#79B8FF">ProductGallery</span><span style="color:#E1E4E8">></span></span></code></pre>

Static asset paths

<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="astro"><code><span class="line"><span style="color:#E1E4E8">&#x3C;</span><span style="color:#79B8FF">ProductGallery</span></span> <span class="line"><span style="color:#B392F0"> images</span><span style="color:#E1E4E8">={images.</span><span style="color:#B392F0">map</span><span style="color:#E1E4E8">((</span><span style="color:#FFAB70">img</span><span style="color:#E1E4E8">, </span><span style="color:#FFAB70">i</span><span style="color:#E1E4E8">) </span><span style="color:#F97583">=></span><span style="color:#E1E4E8"> ({</span></span> <span class="line"><span style="color:#E1E4E8"> src: </span><span style="color:#9ECBFF">`/photos/${</span><span style="color:#E1E4E8">img</span><span style="color:#9ECBFF">.</span><span style="color:#E1E4E8">path</span><span style="color:#9ECBFF">}`</span><span style="color:#E1E4E8">,</span></span> <span class="line"><span style="color:#E1E4E8"> thumb: </span><span style="color:#9ECBFF">`/photos/${</span><span style="color:#E1E4E8">img</span><span style="color:#9ECBFF">.</span><span style="color:#E1E4E8">path</span><span style="color:#9ECBFF">}`</span><span style="color:#E1E4E8">,</span></span> <span class="line"><span style="color:#E1E4E8"> full: optimizedImages[i].src,</span></span> <span class="line"><span style="color:#E1E4E8"> alt: </span><span style="color:#9ECBFF">`${</span><span style="color:#E1E4E8">productNumber</span><span style="color:#9ECBFF">} - ${</span><span style="color:#E1E4E8">productTitle</span><span style="color:#9ECBFF">} [${</span><span style="color:#E1E4E8">i</span><span style="color:#F97583"> +</span><span style="color:#79B8FF"> 1</span><span style="color:#9ECBFF">}/${</span><span style="color:#E1E4E8">images</span><span style="color:#9ECBFF">.</span><span style="color:#79B8FF">length</span><span style="color:#9ECBFF">}]`</span><span style="color:#E1E4E8">,</span></span> <span class="line"><span style="color:#E1E4E8"> }))}</span></span> <span class="line"><span style="color:#E1E4E8">></span></span> <span class="line"><span style="color:#E1E4E8"> &#x3C;</span><span style="color:#79B8FF">Badges</span><span style="color:#B392F0"> badges</span><span style="color:#E1E4E8">={badges} </span><span style="color:#B392F0">class</span><span style="color:#E1E4E8">=</span><span style="color:#9ECBFF">"top-2"</span><span style="color:#E1E4E8"> /></span></span> <span class="line"><span style="color:#E1E4E8">&#x3C;/</span><span style="color:#79B8FF">ProductGallery</span><span style="color:#E1E4E8">></span></span></code></pre>