← Web Components

Web Components · PDP

<mmm-pdp-gallery>

The full product image / video gallery — thumbnail rail, main viewer with badge overlay, video player with play-button overlay, and a hover zoom panel. Driven by PDP_STORE.productInfo.media and re-rendered when the variant changes.

Overview

The gallery has 7 styling surfaces, each fully themable via attributes:

  • Host — outer container (display, width, min-height).
  • Gallery layout — flex / gap / width of the thumbnail-rail-plus-main-image row.
  • Thumbnails — column or row, size, hover / active border, image fit.
  • Main image — width, height, fit, border-radius, plus a positioned badge overlay.
  • Video — sizing, fit, with a styled play button over the poster frame.
  • Zoom — hover zoom panel on desktop, fully positioned + bordered.

60+ inline attributes. Defaults match the theme; every value is overridable.

When to use

  • On every PDP — the primary visual surface.
  • For products with multiple images or a hero video.
  • For apparel / homeware where hover zoom on details closes the sale.

Quick start

<script src="https://v2-api-production.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>

<mmm-pdp-gallery gallery-gap="1.25rem" thumbnail-width="5.625rem"></mmm-pdp-gallery>

Host & layout

AttributeTypeDefaultDescription
host-displaystringblockCSS display on the host.
host-widthstring100%Host width.
host-min-heightstring25remMinimum host height — keeps layout from jumping while images load.
gallery-displaystringflexDisplay for the thumbnail-rail + main-image row.
gallery-gapstring1.25remGap between thumbnail rail and main image.
gallery-widthstring100%Inner row width.

Thumbnails

AttributeTypeDefaultDescription
thumbnails-displaystringflexDisplay for the rail.
thumbnails-flex-directionstringcolumncolumn = vertical rail, row = horizontal strip below the main image.
thumbnails-gapstring0.625remGap between thumbs.
thumbnails-overflow-ystringautoVertical overflow when there are many thumbs.
thumbnails-ms-overflow-stylestringnoneIE / legacy Edge scrollbar style.
thumbnail-widthstring5.625remThumbnail width.
thumbnail-heightstring5.625remThumbnail height.
thumbnail-borderstring2px solid transparentDefault thumb border.
thumbnail-border-radiusstring0.5remThumb border-radius.
thumbnail-cursorstringpointerThumb cursor.
thumbnail-transitionstringborder-color 0.3s easeThumb transition on hover/active.
thumbnail-hover-border-colorstring#000Thumb border on hover.
thumbnail-active-border-colorstring#000Thumb border for the active (currently-shown) thumb.
thumbnail-media-widthstring100%Image / video width inside the thumb.
thumbnail-media-heightstring100%Image / video height inside the thumb.
thumbnail-media-object-fitstringcontainObject-fit for thumb media.

Main image + badge

AttributeTypeDefaultDescription
main-image-flexstring1Flex factor for the main-image area.
main-image-positionstringrelativeCSS position — needed for badge / play-button absolute children.
main-image-backgroundstringtransparentBackground behind the image (visible on letterboxing).
main-image-border-radiusstring0.5remBorder-radius around the main-image container.
main-image-overflowstringhiddenOverflow — keep hidden to clip on the border-radius.
main-img-widthstring100%Image element width.
main-img-heightstring100%Image element height.
main-img-object-fitstringcontainObject-fit for the main image.
main-img-border-radiusstring0.5remBorder-radius on the image itself.
main-img-cursorstringvar(--cursor-style)Cursor on the image (paired with zoom).
badge-positionstringabsoluteBadge position — anchored to the main-image area.
badge-topstring1.25remBadge top offset.
badge-leftstring1.25remBadge left offset.
badge-backgroundstring#000Badge background colour.
badge-colorstring#fffBadge text colour.
badge-paddingstring0.5rem 1remBadge padding.
badge-font-sizestring0.75remBadge font size.
badge-font-weightstring600Badge font weight.
badge-z-indexnumber10Badge stacking context.

Video + play button

AttributeTypeDefaultDescription
video-container-positionstringrelativeVideo container CSS position.
video-container-widthstring100%Container width.
video-container-heightstring100%Container height.
video-container-displaystringflexContainer display.
video-container-align-itemsstringcenterAlign-items.
video-container-justify-contentstringcenterJustify-content.
video-cursorstringpointerCursor on the video element.
video-widthstring100%Video element width.
video-heightstring100%Video element height.
video-object-fitstringcoverObject-fit.
video-border-radiusstring0.5remBorder-radius on the video.
play-btn-positionstringabsolutePlay button position.
play-btn-widthstring5remPlay button width.
play-btn-heightstring5remPlay button height.
play-btn-backgroundstringrgba(0, 0, 0, 0.6)Play button background.
play-btn-borderstring3px solid whitePlay button border.
play-btn-border-radiusstring50%Play button border-radius.
play-btn-transitionstringall 0.3s easePlay button transition.
play-btn-z-indexnumber10Play button stacking.
play-btn-opacitynumber0Play button opacity (revealed on hover).
play-btn-hover-backgroundstringrgba(0, 0, 0, 0.8)Hover background.
play-btn-hover-opacitynumber1Hover opacity.
play-btn-svg-widthstring2remInner SVG width.
play-btn-svg-heightstring2remInner SVG height.
play-btn-svg-fillstringwhiteInner SVG fill.

Hover zoom

AttributeTypeDefaultDescription
zoom-positionstringfixedZoom panel position (the panel is appended to document.body).
zoom-widthstring42vwZoom panel width.
zoom-heightstring60vhZoom panel height.
zoom-borderstring1px solid #cccPanel border.
zoom-box-shadowstring0 0.25rem 0.75rem rgba(0,0,0,0.15)Panel shadow.
zoom-backgroundstringwhitePanel background.
zoom-overflowstringhiddenOverflow inside the panel.
zoom-z-indexnumber9999Panel stacking.
zoom-displaystringnoneDefault display (hidden until hover).
zoom-pointer-eventsstringnonePointer-events while hidden.
zoom-active-displaystringblockDisplay when the panel is active.
zoom-img-positionstringabsolutePosition of the zoomed image inside the panel.
zoom-img-max-widthstringnoneMax-width for the zoomed image (set a value to clamp).
custom-cssstring—Extra CSS appended inside the shadow DOM.

Events

EventTargetPayload
gallery:media-changedhost{ index, mediaUrl }

Live preview

store sample-store tag <mmm-pdp-gallery>

Examples

1. Default

<mmm-pdp-gallery></mmm-pdp-gallery>

2. Horizontal thumbnail strip below main

<mmm-pdp-gallery
  gallery-display="flex"
  custom-css=".gallery { flex-direction: column-reverse; } .thumbnails { flex-direction: row !important; overflow-x: auto; }"
  thumbnail-width="4rem"
  thumbnail-height="4rem">
</mmm-pdp-gallery>

3. Accent badge + pill thumbnails

<mmm-pdp-gallery
  thumbnail-border-radius="999px"
  thumbnail-active-border-color="#c8a8ff"
  thumbnail-hover-border-color="#c8a8ff"
  badge-background="#c8a8ff"
  badge-color="#0e1011"
  badge-padding="0.375rem 0.75rem">
</mmm-pdp-gallery>

4. Disable zoom and use simple cursor

<mmm-pdp-gallery
  main-img-cursor="default"
  zoom-display="none"
  zoom-active-display="none">
</mmm-pdp-gallery>