Configuring color swatches

Color swatches are a powerful feature allowing you to show color options with colored images rather than text. With color swatches, customers can easily visualize your variations and make a buying decision faster.

Native color swatches

If you are using Prestige v9 or higher, Impact v5 or higher, Focal v11 or higher, Warehouse v5 or higher, then your theme can take advantage of native color swatches. Native color swatches allow you to manage your swatch directly from Shopify admin, without the need of any complex setup or code.

Native color swatches leverage Shopify categories to work.

For more information on setting up native color swatches, please check the Shopify documentation.

Vintage color swatches

If you are using an older theme, or cannot upgrade to product categories, you can use the vintage method to setup color swatches.

To be appropriately configured, color swatches require you to follow three steps:

  1. Configuring the color mapping.
  2. Configuring the color option names.
  3. Showing the swatches on product or collection pages.
  4. (Optional) Translating color mapping (if your store is available in multiple languages).

This guide will cover each step.

Configuring the color mapping

When the theme encounters a color name, such as Blue, Navy, or Buffalo Brown, it won't be able to show a color from this name automatically. The theme cannot make an assumption for you on how to render a given color, so you need to help the theme figure out how to show a given color.

Some very simple color names, when written in English (such as Blue, Red, Yellow or Green), are automatically replaced by a color. However, you can also replace those automatically generated color with your own.

This is done through the color mapping. Color mapping will map a color name (such as Navy) to a hexadecimal code or color name. To open the color swatch mapping, open the theme editor, then click on "Color swatch" part:

Pro-tip: you can also configure swatches to appear rounded instead of squared from the color swatch settings.

When configuring the color mapping, you must enter one mapping per line. Each line must be the color name (as written in your product options), followed by the semi-colon character (:), and the hexadecimal code or file name.

Using a hexadecimal code

The most straightforward approach is to use a hexadecimal code. This allows you to create a large number of colors quickly.

If you are unfamiliar with hexadecimal code, you can generate them using an online tool such as Color Picker. The hexadecimal code will appear at the top:

For instance, here is an example mapping that allows displaying the color #ff0000 for the color named Red, and the color #6b483e for the color named Buffalo brown.

When setting your mapping using hexadecimal code, make sure that you follow the rules:

  • The color name must match the color option name in your Shopify admin.
  • Hexadecimal code must start with the hash (#) character.
  • Each rule must be on its line.

Using an image file

Sometimes, using a hexadecimal code may not be enough. For instance, you could have dual colors such as Red-Blue, or patterned colors like Zebra.

For answering such use cases, the theme allows you to map a color name to an image file you create yourself.

1/ The first step is to create an image file representing the color to show. If you are not familiar with creating images, you can hire a graphic designer to make those images for you. We recommend images whose size is 100 x 100px in JPG format.

2/ After creating your image, open the Shopify admin and select the "Files" section:

3/ Upload the image (it can take a few seconds, depending on the size of your image).

4/ Once uploaded, click on the image and note the last part of the URL (it should be the image name followed by the extension). In the screen below, it is zebra.jpg

If you uploaded an image whose name already exists, Shopify might generate a long name with random numbers and letters. You will need to copy the full handle with its extension.

5/ Finally, write your mapping to map the option name to the color name. In this example, the mapping would be:

Mixing both approaches

You can, of course, mix both approaches by using hexadecimal code whenever possible and using files only when necessary.

Configuring the option names

The theme will only show color swatches if the product option name is called Color or Colour (for stores in English).

If your store is not English, the theme will look for a name in your preferred language. For instance, a store in French will show color swatches if the option name is Couleur, while a store in Japanese will look for an option named カラー.

However, you may want to show color swatches for different options, such as Material or Finish. The theme cannot automatically guess your intent, so you must instruct the theme which option name must be considered as a color.

To do that, follow the steps below:

1/ In the theme list in Shopify admin, click on the "Edit default theme content" button:

2/ Filter the sentences with Color to show the sentence to edit:

3/ The Color sentence holds which option name must be considered a color swatch. You can enter a list of comma-separated option names. For instance, the setting as shown below will show any option named Color, Colour, Material or Finish as a color swatch:

Showing the swatches

Once you have configured color mapping, the last step is to enable the color swatches on product or collection pages.

Product pages

1/ Open the theme editor, and navigate to the Product section:

2/ In the product page template, select the Variant picker block:

3/ Select Color swatch for the Color selector type setting:

Collection pages

To show color swatches on product listings (such as collection pages), open the theme editor, open the Theme Settings, select the "Product card" section, and select "Swatch" for the Color display mode setting:

Enabling color swatches on product cards will display swatches on every product listing, including collection pages and the featured collection section.

(Optional) Translating color mapping

If your store is available in multiple languages, you must translate the mapping into each languages. For instance, a color named Red in English may be named Rouge in French. However, the color mapping only controls your store's primary language. This section will also guide you on configuring color swatches for other languages.

Those instructions assume you are using the free Translate & Adapt app from Shopify. If you are using a different translation app, please reach the app developers.

1/ Ensure the mapping has been properly defined for your primary language.

2/ Open the Translate & Adapt app. In the app, ensure that the language you want to translate is selected.

3/ Click on the Edit button for the Theme settings category:

4/ On the left sidebar, select Color Swatch:

5/ The original mapping will appear on the left, while the translated one will appear on the right (the first time, it will be empty, meaning it has not been translated yet):

6/ Translate the mapping, by ensuring that you properly adjust the color name with the translated product option values. For instance, if your product option Red is translated as レッド in Japanese, here is how the mapping would look like:

Most of the time, only the left part before the semi-colon must be translated. The right part (either the hexadecimal code or the file name) won't change.


  • Can we set up different color swatches for the same color name? Having different colors for the same color name (for instance, a different color based on the product) is not possible. You can have only one rule per color. If you need to have different swatches for the same color name, you need to hire a developer.
  • Can swatches be translated? Yes, color swatches can be translated if you are using multiple languages. Refer to the section Translating color mapping on this page for more information.
  • Do color swatches reduce performance? The theme tries to optimize color swatches as much as possible. However, if you have products with a lot (20+) color options, we recommend turning off swatches on collection pages.
  • Can I show variant images instead of swatches? Instead of showing color swatches, you can instead show variant images for colors. Learn more about this feature.