← Web Components

Web Components · PDP

<mmm-pdp-variants>

Full variant picker for the PDP. Detects option types from PDP_STORE.productInfo.options and renders tab (text), color (swatch), or img (thumbnail) controls. Selection writes to the store; downstream price, gallery, and add-to-cart components react.

Overview

Three control families with independent styling. Each option in the product's option list is grouped under a label and rendered using the type that matches its data (text label → tab, hex / colour name → color swatch, image URL → img). Out-of-stock variants render with a struck-through state.

When to use

  • On every PDP for products with two or more variants.
  • For colour-driven products (apparel, accessories) — colour mode auto-selects.
  • For visual collections (prints, patterns) — image mode auto-selects.

Quick start

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

<mmm-pdp-variants></mmm-pdp-variants>

Attributes

60+ inline attributes grouped by control family — text tabs, colour swatches, image swatches, and native dropdown.

AttributeTypeDefaultDescription
section-positionstringrelativeCSS position on the outer block.
option-margin-bottomstring1.25remGap between option groups.
label-font-sizestring1remOption-name label font size.
label-font-weightstring600Label font weight.
label-margin-bottomstring0.75remSpacing below the label.
label-displaystringblockSet none to hide labels.
tab-displaystringflexDisplay of the text-option row.
tab-gapstring0.5remGap between text options.
tab-flex-wrapstringwrapFlex-wrap behaviour.
tab-btn-paddingstring0.5rem 1.25remText option button padding.
tab-btn-heightstring3.125remText option button height.
tab-btn-borderstring1px solid #dddDefault border.
tab-btn-border-radiusstring0.25remBorder-radius.
tab-btn-backgroundstring#fffDefault background.
tab-btn-cursorstringpointerCursor.
tab-btn-font-sizestring0.875remFont size.
tab-btn-transitionstringall 0.3s easeHover transition.
tab-btn-hover-border-colorstringtheme button hoverStroke / #e5e7ebBorder colour on hover.
tab-btn-selected-borderstring2px solid theme button fillBorder for the selected option.
tab-btn-selected-backgroundstringtheme button fill / #000Background of selected option.
tab-btn-selected-colorstringtheme variant text / #fffText colour of selected option.
tab-btn-selected-font-weightstring600Selected font weight.
color-btn-paddingstring0.25remPadding around colour swatch (drives outer ring).
color-btn-borderstring1px solid #dddDefault outer border.
color-btn-border-radiusstring50%Outer border-radius.
color-btn-cursorstringpointerCursor.
color-btn-transitionstringall 0.3s easeTransition.
color-btn-backgroundstring#fffOuter background.
color-btn-hover-border-colorstringtheme button hoverStroke / #e5e7ebOuter border on hover.
color-btn-selected-borderstring2px solid theme button fillOuter ring for selected swatch.
color-btn-selected-box-shadowstring0 0.125rem 0.5rem rgba(0,0,0,0.15)Shadow for selected state.
color-inner-widthstring2.5remInner colour disc width.
color-inner-heightstring2.5remInner colour disc height.
color-inner-border-radiusstring50%Inner border-radius.
color-inner-box-shadowstring0 0 0 0.0625rem rgba(0,0,0,0.1)Inner subtle outline for light colours.
img-btn-widthstring3.75remImage swatch width.
img-btn-heightstring3.75remImage swatch height.
img-btn-borderstring1px solid #dddDefault border.
img-btn-border-radiusstring0.25remBorder-radius.
img-btn-cursorstringpointerCursor.
img-btn-overflowstringhiddenOverflow handling.
img-btn-transitionstringall 0.3s easeTransition.
img-btn-hover-border-colorstringtheme button hoverStroke / #e5e7ebBorder on hover.
img-btn-selected-borderstring2px solid theme button fillBorder for the selected image swatch.
img-btn-selected-box-shadowstring0 0.125rem 0.5rem rgba(0,0,0,0.15)Shadow for selected image swatch.
img-btn-selected-opacitystring1Image opacity when selected.
img-btn-not-selected-opacitystring0.7Image opacity when not selected.
dropdown-wrapper-widthstring100%Width of the dropdown wrapper.
dropdown-wrapper-positionstringrelativeCSS position of the wrapper.
dropdown-widthstring100%Width of the native select.
dropdown-paddingstring0.75rem 2.5rem 0.75rem 0.75remPadding (right side reserved for arrow).
dropdown-borderstring1px solid #dddBorder.
dropdown-border-radiusstring0.25remBorder-radius.
dropdown-font-sizestring0.875remFont size.
dropdown-backgroundstring#fffBackground colour.
dropdown-cursorstringpointerCursor.
dropdown-background-positionstringright 0.75rem centerPosition of the inline arrow SVG.
dropdown-transitionstringall 0.3s easeTransition.
dropdown-hover-border-colorstringtheme button hoverStroke / #e5e7ebBorder on hover.
dropdown-focus-border-colorstringtheme button fill / #000Border on focus.
dropdown-focus-box-shadowstring0 0 0 0.125rem rgba(0,0,0,0.1)Focus ring.
dropdown-option-paddingstring0.5remPadding on dropdown <option> elements.
custom-cssstring—Extra CSS appended inside the shadow DOM.

Events

  • variant:selected — fired on click with { optionName, variantCode, allVariants }.
  • variant:combination-checked — fired after the combination API returns with { variants, combinationDetails }.

Live preview

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

Examples

1. Default — theme-driven

<mmm-pdp-variants></mmm-pdp-variants>

2. Larger swatches, pill text buttons

<mmm-pdp-variants
  color-inner-width="1.5rem"
  color-inner-height="1.5rem"
  img-btn-width="3.5rem"
  img-btn-height="3.5rem"
  tab-btn-border-radius="999px"
  tab-btn-padding="0.5rem 1rem">
</mmm-pdp-variants>

3. Dark-mode accent rings

<mmm-pdp-variants
  tab-btn-border="1px solid #2a2e33"
  tab-btn-selected-border="2px solid #c8a8ff"
  tab-btn-selected-background="#c8a8ff"
  tab-btn-selected-color="#0e1011"
  color-btn-selected-border="2px solid #c8a8ff"
  img-btn-hover-border-color="#c8a8ff">
</mmm-pdp-variants>