Prerequisites

A synced product detail page and a Shopify product with real options and product images. Variant-specific image behavior requires images assigned to variants.

1. Check the source product

Review the options and images in Shopify first. Use a product with multiple selectable values so you can test selected and unavailable states. Sync the managed product CMS after source changes.

2. Connect a selector

Insert Variant Selector or Option Selector and bind Product Data. Variant Selector manages option selection and automatically hides for products without variants. Option Selector can present buttons or a dropdown. Start with the standard controls before building a custom selector.

3. Set clear selection states

Style selected, hover, and unavailable values so they remain distinct on black surfaces. Variant Selector can hide unavailable values or show them with reduced opacity. For custom color mappings, match Shopify option names to the intended colors.

4. Connect the gallery

Insert Image Gallery and bind the same Product Data. Set its direction, gap, main-image aspect ratio, and thumbnail treatment. The gallery automatically changes to a variant image when the product has variants with images.

5. Verify purchase controls together

Bind Price and Add to Cart to the same product. Select multiple variant combinations, inspect image and price changes, and add a chosen variant to the cart. Check the resulting variant label rather than relying only on the button animation.

Check your work

The selected option should be clear, the gallery should respond where variant images exist, and the cart should contain the chosen variant. Test a product without variants too: selector visibility should remain sensible.

Troubleshooting

If a selector disappears, confirm that the product actually has variants. If media does not change, check variant image assignments in Shopify. If controls disagree, check Product Data at every component layer and sync the CMS again.

Resources

Product Components Reference