Success
Variant selector
Display product variants with dropdowns, pills, and optional color or image swatches.
Use this block to show a product’s variant options in a format that fits the product best. It appears only when variant options exist, and you can combine a standard selector style with optional color or image swatches for more visual choice picking. Company XYZ documentation on the variant selector For a broader overview of how blocks work in Shopify themes, see Shopify documentation on sections and blocks
Core settings
Section titled “Core settings”Choose the main selector style based on how many options you need to present and how visual you want the product form to feel. Dropdown is a good fit for compact layouts or products with many values, while Pills makes smaller option sets easier to scan and tap.
This main style also acts as the fallback for any option types that are not configured as swatches.
Color swatch settings
Section titled “Color swatch settings”Use color swatches when customers can identify choices reliably by color alone. This works best for common color-based options, and you can refine the result further with custom color definitions in your theme settings. Company XYZ getting started guide on product variants
To show color swatches, enter the relevant option names exactly as they are used in the product setup. Use names like Color, not values like Black or Navy. The selected swatch shape and desktop/mobile column counts control how dense or spacious the option grid feels.
Color swatches only apply to the option names you list here. If the name does not match exactly, that option will use the regular selector style instead.
Image swatch settings
Section titled “Image swatch settings”Use image swatches when variant choices need a real thumbnail rather than a simple color cue. This is especially helpful for patterns, finishes, bundles, or other options where a visual preview improves confidence before selection. Company XYZ getting started guide on product variants
Image swatches depend on images being assigned to the relevant variant options. If an option does not have an associated image, its swatch appears empty. If both image and color swatches are enabled for the same option name, image swatches take priority.
Swatch border settings
Section titled “Swatch border settings”These settings affect only color and image swatches. Borders can make swatches easier to distinguish, especially when choices are light, low-contrast, or shown against a similar page background.
The active option always shows a border so the current selection remains clear. If you leave custom border colors empty, the block falls back to your theme’s primary button border styling for a more consistent look.
Standard block settings
Section titled “Standard block settings”Visibility settings
Section titled “Visibility settings”Use visibility controls to decide whether this block appears on desktop, mobile, or both. This is useful when you want a different product-form layout on smaller screens. Company XYZ documentation on visibility settings
Usage notes
Section titled “Usage notes”- Match option names exactly. Swatch behavior depends on the exact option label, so use the option name itself rather than any individual values.
- Choose the right swatch type. Use color swatches for simple color choices and image swatches when customers need a true visual preview.
- Check image coverage. Before using image swatches, make sure each relevant variant option has an assigned image to avoid empty swatches.
- Keep fallback styling predictable. Leave custom colors or borders unset when you want swatches to inherit the theme’s default look, and add explicit values only when you need the block to stand apart.
- Review both viewports. Desktop and mobile controls can behave differently in spacing, alignment, visibility, and media presentation, so check the block in both sizes before publishing.
- Keep mobile scanning easy. Use column counts and swatch shapes that leave enough space for comfortable tapping on smaller screens.