Variant selector


What is the Variant selector block?

The Variant selector block controls the interface for selecting a product’s variant options. The block is available in the Product information section (the main section of Product templates), and in the Featured product section (which you can add to any template).

An overview of the Variant selector block

Important note

This Variant selector block will not show if no variant options exist for your product. But it’s important to note that the Variant selector block is required for products with variants; the add to cart function will not work otherwise (again, if the product has variants).

Showing the Variant selector block on a product without variants

Core settings

The Variant selector block is deceptively powerful: we've provided some simple-but-nuanced settings to give you the most flexibility for your specific product and variant types.

These core settings control how the variant interface (the "UI") will be displayed in your template. Different templates can obviously have different Variant selector block settings, so you can set these up differently depending on a specific product or collection for ultimate flexibility 😎

You can see the Variant selector block in use in the examples below.

Variant selector style

This is the most basic layout setting: to put the variant options within a dropdown/select menu or within “pill”-style buttons.

Default. This is the default block layout which is set to show variant options within dropdown menus (for SizeColor, and Sleeves in the example):

Dropdown style

[ Section - Featured product - Default ]

Pills style

And here we're showing the Pills option for the Variant selector style setting.

[ Section - Featured product - Pills ]


As opposed to the dropdown select or pill button style for your variant selector, swatches are visual representations of product variants. Using swatches can that have a number of benefits:

  1. Simplifies the variant selection process and enables customers to easily compare and choose the variant they want.
  1. Provides instant visual feedback to customers by changing the main product image when a swatch is selected.
  1. Reduces cognitive load and decision fatigue by presenting options visually. (Cha-ching! 🤑)
  1. Improves the visual appeal of a page by adding an interactive color component.
  1. Improves the layout of a product section, as swatches are a space-efficient way to present multiple options, compared to text or buttons.
  1. Allows for more precise representation of colors and patterns, ensuring that the product's appearance on the website is consistent with the brand's aesthetic.

There are two types of swatches

  1. Color swatches, i.e. the primary color of your product or variant.
  1. Image swatches, i.e. the thumbnail of your product or variant.

We’ve built awesome and easy-to-use implementations for each type. They might be a little tricky to wrap your head around at first, but we promise you’ll be an expert in no time!

[ Section - Featured product - Color and image swatches ]

Color swatches


An overview of color swatches

We built color swatches to be as “automatic” as possible, but with the added flexibility of full customization for your unique products or use-case. Color swatches will automatically attempt to use the option’s name as the named-color of the swatch, e.g. a “Black” option would use #000000 by default.

You can create custom color definitions via the Custom color swatches setting within the Color settings of your Theme settings. Learn more below.

How to enable color swatches

  1. Navigate to a product template in the theme editor.
  1. Find the Product information section, then find the “Variant selector” block.
  1. Select the enable color swatches checkbox.
    1. Please note that this will overwrite the Variant selector style setting, i.e. the dropdown or pill style setting will not apply.
  1. Add the variant option name(s) that should display the color swatches to the Color swatch Option names setting.
    • Important: Use the actual variant option name, not the option values.
      • e.g. In the screenshot below, you would use "Color," not the option values, such as "Black, Brown, Blue".
      • Note that this also works for translated values: for example if you had English, French and Lithuanian languages installed into your store via the Shopify Translate & Adapt app, you could enter “Color” or “Couleur” or “Spalva.”
    • You can also add multiple, comma-separated variant option names to display multiple variant options as swatches.
  1. By default, the color swatches will take the name of the variant and try to use it as a background color of the swatch.
    1. Reference CSS named colors for information about how these colors will look.
  1. Optional: If custom values are needed, those values can be defined in theme settings.
    1. Navigate to Theme settings in the Theme editor.
    1. Open the “Colors” setting group and scroll to find the “Custom color swatches” setting
    1. Enter comma-separated definitions for an option value and it's custom HEX value in this format: “Black: #000, Red: #ff0000” (without quotes).
      1. You can have one definition, or many — just separate each with a comma!
    1. Pro-tip: If you want to use something like "Material" as a color swatch, but the variant option values are not actually colors, you must add this definition to theme settings; otherwise empty swatches will be displayed.
Display a custom color swatch by updating the option value
Display a custom color swatch via Theme setting override

Image swatches


An overview of image swatches

[ Section - Featured product - Image swatches ]

Image swatches will display the thumbnail which has been set for each variant option. If an option does not have an associated image, it will appear empty. Image swatches will override color swatches if both types are used.

How to enable image swatches

  1. Navigate to a product template in the theme editor.
  1. Find the Product information section, then find the “Variant selector” block
  1. Select the "enable image swatches" checkbox
    1. Please note that this will overwrite the Variant selector style setting, i.e. the dropdown or pill style setting will not apply.
  1. Add the variant option name(s) that should display the image swatches to the Image swatch Option names setting.
    1. Some important notes:
      1. Color swatches and image swatches can be combined in one product.
      1. There can only be one image swatch on a single product/variant.
      1. A variant might use multiple options (e.g. Size “Small” and Color “Black”). In this case, the image swatch will use the variant image for that specific variant combination.
      1. If you are attempting to show image swatches for multiple variant options (e.g. you want to show image swatches for both “Color” and “Material” options), and the same image would be used for both values, then the secondary option group will show the default UI.
        1. e.g. if “Color” and “Material” options would actually show the same image, then we only show the image in the “Color” UI (or whatever is listed earlier in the setting).
        1. Otherwise you’d be showing the same image multiple times, which will be confusing for your customers!

Swatch style settings


Both swatch types have several settings which will allow you to fully customize how your swatches are displayed.

Swatch style

We’ve provided a few swatch styles to give you even more control over how your variant swatches are displayed.

  • Default
    • Only available for image swatches.
    • Will display the image in its “natural” aspect ratio, e.g. if the original variant image is a square, it will appear as a square here.
  • Circle
  • Landscape
  • Portrait
  • Square
  • Widescreen
An overview of swatch style settings

Column count

Desktop and mobile settings. A simple, yet powerful way to control the width of your swatches.

This setting is pretty self-explanatory, but thinking in “columns” instead of pixel-based widths can be a little confusing at first. Play around with these settings and we think you’ll get the idea quickly — we think it’s a quicker/easier way to create clean, responsive (i.e. mobile-friendly) layouts.

A few notes:

  • There is a minimum width of one column and a maximum width of 8 columns.
  • The columns will control the actual width of the color and/or image swatches, and will automatically load the best image size.
  • There are different settings for desktop and mobile. Be sure to check out the mobile view of your template and update them to be the best and most usable for your mobile customers. Don’t forget to QA your templates in the mobile view!
An overview of swatch column settings