Use custom images

Variant swatches

Theme retirement | Context is no longer available on the Shopify theme store. Theme support and updates for current users will end after May 18, 2024. Learn more here.

Using custom images for swatches is great for product variants that have patterns or textures. Custom swatch images require image file names and variant names that match, which we will cover below.

Adding custom swatches images involves two general steps: (1) Create and upload your custom swatch images and (2) Set up your product variants with matching names.

1. Create and upload custom swatch images

For each product variant, you need to create a PNG image by screenshotting or cropping your product images. Each swatch image needs a file name that matches the variant name in your product options.

For example, if the product variant is called "Sea Blue", the swatch image file must be named sea-blue.png.

If your store uses multiple languages, make sure to upload swatch images with file names that match the translated name of your product variants, for each language.

For example, if your store uses English and German, you need two swatch image files for the default variant name (yellow.png) and the translated name (gelb.png).

STEPS

You can create PNG image files by taking a screenshot (step 2) or cropping your product images (step 3).
We recommend images with minimum length or width of 70px.
Screenshots: Use the built-in screenshot tool on your computer to capture swatches from your existing product images:
Windows: How to use Windows Snipping Tool
Mac: Take a screenshots on your Mac
Cropped images: Alternatively, crop a section of your product photo with a photo editing application (like Preview or Photoshop).
Windows: How to Crop Images on Windows
Mac: How to crop an image in Preview on Mac
Save your images as PNG files with a file name that matches the variant name. File names must be in lowercase and use hyphens instead of spaces. Add image files for each store language matching the translated variant name.
For all image files, use lowercase only (no capitals):
Variant name File name
For variants with multiple words, use hyphens - instead of spaces:
Variant name File name
For multiple languages, add image files for each language with the translated names of the product variant:
Language Variant name File name
Once you have renamed your swatch images, go to Content > Files in your Shopify admin.
Click the Upload files button in the top-right corner and add all your swatch image files. You can select multiple files at once.
Go to Step two: Set up your product variants.

2. Set up product variants

Once you've uploaded your images, you need to set up your product variants with names that match the file names of your swatch images.

STEPS

In your Shopify admin:

Go to Products and click the product you want to edit.
Under Variants, click Add options like size and color checkbox if you're adding variants for the first time.
Add the Option name (e.g. "Color" or "Material").
Remember to add this option name in your Theme settings to enable swatches.
See Shopify's Variants guide for more information about product options.
Add the Option values (product variants) with a name that corresponds to the correct swatch image file.
For example, if you've uploaded dark-blue.png as a swatch image, the product variant must be named Dark Blue.
If your store uses multiple languages, add the translated variant names using Shopify's Translate & Adapt feature.
Variant name File names
Preview your store to confirm that the swatches now appear.
If the theme cannot locate a matching swatch image for a color variant, a White swatch is shown. In this case, make sure the file names match the variant name, use hyphens - instead of spaces, and are all lowercase (no capitals).
Click Save.