How to set up color and image swatches

Make an option like Color render as swatches in the variant picker and on product cards, with flat colors, custom images, or variant images.

Any product option whose name matches the Swatch option names field on the Variant picker block (default "Color, Colour") renders as a swatch automatically, as long as a matching swatch entry exists. Text swatches aren't a separate mode: any value without a matching entry falls back to its text label.

Create the swatch metaobject entries

  1. In Shopify admin, go to Content > Metaobjects.
  2. Find the Squiggle and code swatch definition and click Add entry.
  3. Set the handle to match your option value exactly, lowercased and hyphenated. For example, an option value of "Pink/White" needs the handle "pink-white".
  4. Fill in Color one (required). Add Color two as well if you want a two-tone, split swatch.
  5. For an image swatch instead of a flat color, upload a file to the Image field.
  6. Click Save, then repeat for every option value you want a swatch for.

Choose the swatch style

  1. Open the theme editor and select your product page, or a Featured product section.
  2. Click into the Variant picker block.
  3. Confirm the option's name is listed in Swatch option names (comma-separated, case-insensitive).
  4. Set Swatch style to Color swatch, Image swatch, or Product image. Color swatch and Image swatch use the metaobject entries above; Product image pulls the linked variant's first image with no metaobject needed. Any style falls back to the flat color when its image is missing, and to the text label when there is no swatch entry at all.

Show swatches on product cards

Swatches can also appear on product cards, everywhere cards show (collection pages, featured collections, search, and so on). They use the same metaobject entries, so once those exist there's nothing extra to create.

  1. Open the theme editor and go to Theme settings > Product card.
  2. Under the Color swatches header, turn on Show color swatches.
  3. Confirm the option's name is listed in Swatch option names (comma-separated, case-insensitive).
  4. Pick a Swatch style: the same three styles and fallbacks as the variant picker, except a value with no swatch entry falls back to a small text chip.

Each card swatch links to its variant, so customers land on the product page with that color preselected.

If you have any questions or issues, send us a message, we're more than happy to help you out!