Commmerce Docs
← Web Components

Web Components · Product

<mmm-product-variants>

Inline variant picker for a product card — colour swatches, image swatches, and text-based options like size. Selecting a variant updates the per-product store, which in turn re-renders price, media, and add-to-cart for that variant.

Overview

The element auto-detects option type from the product data: colour-named options render as circular swatches; image-typed options render as small image thumbs; any other option (size, fit, length) renders as a text chip. Selection writes the chosen option to the shared store via setSelectedVariant(); the store then dispatches commmerce:variant-selected on window.

When to use

  • Inside <mmm-product-card> for products with multiple variants.
  • For colour-swatch grids where the user picks a colour before clicking through to the PDP.

Quick start

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

<mmm-product-card data-product='{"slug":"classic-tee","options":[{"name":"Color","values":["Black","White","Charcoal"]}]}'>
  <mmm-product-variants color-size="1.25rem" gap="0.5rem"></mmm-product-variants>
</mmm-product-card>

Attributes

AttributeTypeDefaultDescription
gapstring0.375remCSS gap between option items.
item-paddingstring0.25rem 0.5remPadding inside each text option chip.
item-border-radiusstring0.25remBorder-radius for text option chips and image swatches.
color-sizestring1.125remWidth & height of circular colour swatches.
image-sizestring2.25remWidth & height of image swatches.
item-hover-border-colorstringtheme accentBorder colour of an option on hover.
item-selected-border-colorstringtheme primary textBorder colour of the selected option.
item-selected-backgroundstringtheme primary textBackground colour of selected text option chips.
item-selected-colorstringtheme product bg / #fffText colour of selected text option chips.
custom-cssstring—Extra CSS appended inside the shadow DOM.
classstring—Standard HTML class list.

Events

Does not emit events directly. Updates are written to the shared product store, which dispatches commmerce:variant-selected on window with { slug, variant }.

Live preview

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

Examples

1. Default colour swatches

<mmm-product-variants></mmm-product-variants>

2. Larger swatches with accent selection ring

<mmm-product-variants
  color-size="1.5rem"
  gap="0.625rem"
  item-selected-border-color="#c8a8ff"
  item-hover-border-color="#c8a8ff">
</mmm-product-variants>

3. React to variant changes globally

window.addEventListener('commmerce:variant-selected', (e) => {
  console.log('Variant chosen on', e.detail.slug, '→', e.detail.variant);
});