Product variants

Featured links

1. Shopify blog: Swatches
2. Shopify developer documentation on the swatch object
3. MDN documentation on named colors
4. Shopify documentation on adding variants
5. Shopify Translate & Adapt app
6. Shopify documentation on adding color swatches using category metafields

Helpful videos

Shopify Academy video: Customizing your store

Shopify Academy video: Customizing your store

Use Align’s Variant selector block to let customers choose product options such as size, color, or sleeve length. Add the block to the Product information section on a product template or to a Featured product section on another template.

For product and variant setup in Shopify, see Shopify documentation on adding variants

Products with variant options need a Variant selector block for the add-to-cart action to work. The block does not display for products with no variant options.

Variant selector styles

Choose how standard variant options appear in the selected Align template. Each Variant selector block has its own settings, so you can tailor the experience for different products or collections.

Dropdowns and pills

Use the Variant selector style setting to choose one of the following layouts:

• Dropdowns are the default layout and place options such as Size, Color, and Sleeves in select menus.

  Dropdown style

• Pills display options as selectable buttons.

  Pills style

Swatches

Swatches are visual variant controls that can make options easier to compare than text-only dropdowns or buttons. They can provide visual feedback, support a more compact layout, and help customers identify colors, patterns, or product imagery quickly.

Align supports two swatch types:

1. Color swatches display a color for an option value.
2. Image swatches display the thumbnail assigned to a variant option.

Color swatches

Color swatches automatically try to match an option value to a named CSS color. For example, an option value of Black uses #000000 by default. Add custom color definitions when option values need a specific color treatment.

Enable color swatches

1. Open a product template in the Shopify theme editor.

2. In the Product information section, select the Variant selector block.

3. Enable color swatches.

   [!NOTE] Color swatches override the selected Variant selector style, so the affected option no longer uses dropdown or pill controls.

4. Enter the variant option name or names in Color swatch Option names.

   • Use the option name, such as Color, rather than its values, such as Black, Brown, Blue.
   • You can enter multiple option names separated by commas.
   • Translated option names also work. For example, stores using the Shopify Translate & Adapt app can use Color, Couleur, or Spalva.

5. Preview the swatches. By default, each swatch uses its option value as a color name. Refer to CSS named colors for available named colors.

6. Add custom color values when needed.

   1. Open Theme settings in the theme editor.
   2. Open Colors and find Custom color swatches.
   3. Enter comma-separated option-value and HEX-color pairs, for example: Black: #000, Red: #ff0000.

For category-metafield color setup, see Shopify documentation on adding color swatches using category metafields

If you use a non-color option such as Material as a color swatch, define each value in Custom color swatches. Without a matching definition, the swatches appear empty.

Image swatches

Image swatches display the thumbnail assigned to each variant option. An option without an associated image appears empty. When both color and image swatches apply to the same option, image swatches take priority.

Enable image swatches

1. Open a product template in the Shopify theme editor.

2. In the Product information section, select the Variant selector block.

3. Enable image swatches.

   [!NOTE] Image swatches override the selected Variant selector style for the affected option.

4. Enter the variant option name or names in Image swatch Option names.

Image swatch behavior

• Color and image swatches can be combined. A product can use different swatch types for different option groups.
• Each variant supports one image swatch.
• Variant combinations use their specific image. For example, a variant with Small and Black options uses the image assigned to that exact combination.
• Repeated images display once. If multiple option groups would use the same image, only the option listed first in the setting displays an image swatch. Later option groups use the default interface to avoid showing the same image repeatedly.

Swatch style settings

Both color and image swatches include display settings for adjusting their shape and layout.

Swatch style

Choose a swatch style that suits the product imagery and available space:

• Default displays image swatches in their natural aspect ratio. This option is available only for image swatches.
• Circle
• Landscape
• Portrait
• Square
• Widescreen

Column count

Use separate desktop and mobile column settings to control swatch width in a responsive layout. Higher column counts create narrower swatches, while lower counts create wider swatches.

1. Choose between one and eight columns.
2. Check both desktop and mobile views, then adjust each setting for a comfortable tap target and readable layout.
3. The column count controls the width of color and image swatches and automatically uses an appropriate image size.

Tip

Always preview swatches on mobile, especially when products have many option values. A column count that works on desktop can make swatches too small or crowded on smaller screens.

Usage notes

1. Keep a selector block available. Products with variants need the Variant selector block for customers to add the selected variant to the cart.
2. Use exact option names. Enter option labels such as Color or Material, not individual option values, when enabling swatches.
3. Define non-standard colors. Add custom color definitions for values that are not recognized color names to prevent empty color swatches.
4. Assign variant images carefully. Image swatches depend on images assigned to the relevant variant combinations.
5. Check mobile layouts. Review mobile column counts and swatch sizes before publishing changes.