> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/avante-themes/features-and-advanced-setup/variant-images-vs-color-swatches.md).
# Variant images vs Color Swatches
Compare Avante's two color display methods — variant images (thumbnails) vs color swatches (circles) — with setup steps and troubleshooting tips.
In Avante, color variants can be shown in two ways: **Variant images** or **Color swatches**. Choose the option that fits how you want customers to shop.
| | Variant images | Color swatches |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shows | Small product thumbnail per color | Small color circle per color |
| Best for | Products with distinct photos per color | Cleaner, simpler selector |
| Example | | |
{% hint style="warning" %}
**If each color is a separate product**, see [Linked Products](/docs/avante-themes/features-and-advanced-setup/linked-products.md) instead — the settings on this page apply to native Shopify variants only.
{% endhint %}
{% hint style="success" %}
**Capitalization doesn't matter.** Avante compares the Variant label with your option name in lowercase, so `Color`, `color` and `COLOR` all match an option named **Color**. Spelling still has to match: `Color` will not match an option named `Colour`.
{% endhint %}
***
### Set up variant images
Variant images show a small thumbnail of the actual product photo for each color option.
{% stepper %}
{% step %}
Go to **Theme Editor → Theme settings → Variant selector**
{% endstep %}
{% step %}
Scroll to **Variant image**
{% endstep %}
{% step %}
Enter your option name in **Variant label** (e.g. `Color`)
{% endstep %}
{% step %}
Optionally adjust shadow, image ratio, focal point, corner radius
{% endstep %}
{% endstepper %}
{% hint style="info" %}
**You can list more than one label here.** Separate them with commas — `Color, Shade, Finish` — and every matching option gets thumbnails. Each label is matched as a whole word, so `Color` will not activate an option named `Color family`.
{% endhint %}
***
### Set up color swatches
Color swatches show a small color circle instead of a product photo.
{% stepper %}
{% step %}
Go to **Theme Editor → Theme settings → Variant selector**
{% endstep %}
{% step %}
Scroll to **Color pills.** Enter your option name in **Variant label** (e.g. `Color`)
{% endstep %}
{% endstepper %}
With no further setup, Avante colors each circle from the **last word** of the option value, read as a standard HTML color name — `Ocean Blue` renders as blue, `Light Grey` as grey. If your store also uses Shopify's own swatch values on option values, Avante picks those up automatically. Everything below is for the cases where neither gives you the shade you want.
***
### Enable swatches on collection cards
By default, swatches appear on the product page only. To show them on product cards in collections:
{% stepper %}
{% step %}
#### Turn the swatches on for the section
Go to **Theme Editor → \[your collection section] → section settings** and enable **Enable color pills**.
This setting lives in each section separately — Featured collection, Collection page, Search results, and so on.
{% endstep %}
{% step %}
#### Choose what the pills show
Go to **Theme settings → Product card → Pills** and pick **Variants**, **Linked product** or **Both**.
{% endstep %}
{% step %}
#### Tell Avante which options are colors
Go to **Theme settings → Product card → Color labels** and list every color option name used in your store, separated by commas — for example `Color, Shade`.
Leave it empty and Avante falls back to any option whose name contains “Color” or “Colour”.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**Product cards use Color labels, not the Variant label from the Variant selector.** If your color option is named something else — `Gemstone`, `Wood`, `Finish` — the product page will show pills as soon as you enter that name in the Variant selector, but collection cards stay empty until you add the same name to **Color labels**.
{% endhint %}
{% hint style="info" %}
**Cards show up to four swatches.** Any colors beyond the fourth are summarised as a `+2` counter next to them. Cards also list in-stock variants only, so a sold-out color is left out of the card entirely — on the product page the same color is shown dimmed instead.
{% endhint %}
***
### Set up custom color swatches
If the color name doesn't resolve, or the displayed shade looks wrong, you can override it in two ways.
### Option A — Upload PNG files
{% stepper %}
{% step %}
#### Set Style to Image in Theme settings
1. Go to **Theme Editor → Theme settings → Variant selector → Color pills**
2. In the **Variant label** field enter your option name (e.g. `Color`)
3. Set **Style** to **Image**
{% endstep %}
{% step %}
#### Prepare the image files
Create **PNG** files for your color values. Name each file after the option value, **keeping its capitalization**, and replace spaces and punctuation with underscores.
* `Red` → `Red.png`
* `Ocean blue` → `Ocean_blue.png`
* `Rose Gold` → `Rose_Gold.png`
Apostrophes, quotes, dots, `&`, `/`, `|`, `?`, `!` and accented letters become underscores too, and two underscores in a row collapse into one.
Recommended: **60×60px**, under **20KB**
{% endstep %}
{% step %}
#### Upload the files in Shopify
In Shopify admin, go to **Content → Files**. Upload the prepared images.
{% endstep %}
{% step %}
#### Let Avante match the files automatically
After upload, Avante links each image to every variant with that value, across your whole store — you don't attach files to products.
{% hint style="info" %}
Only `.png` is looked up. A `.jpg` or `.webp` file with the right name is ignored.
{% endhint %}
{% endstep %}
{% endstepper %}
### Option B — Define hex colors in Theme Editor
Faster when you only need solid colors.
{% stepper %}
{% step %}
Go to **Theme Editor → Theme settings → Variant selector**
{% endstep %}
{% step %}
Scroll to **Custom colors for pills → Configuration**
{% endstep %}
{% step %}
Add one rule per line:
```
VariantName:#hexcolor
```
Example:
```
Red:#ff0000
Ocean Blue:#4a90d9
Bubble Pink:#f5b8c4
```
{% endstep %}
{% endstepper %}
{% hint style="success" %}
**Here capitalization doesn't matter either.** `Ocean Blue`, `ocean blue` and `OCEAN BLUE` all match the same option value.
{% endhint %}
{% hint style="info" %}
Use PNG files when you need textures, patterns, or photographic swatches. For solid colors, the Configuration field is quicker. If you set up both for the same value, the uploaded PNG wins.
{% endhint %}
***
### Common issues
Swatches are not showing at all
Check the spelling of **Variant label** against your product option name. Capitalization is ignored, but the spelling has to match — `Color` will not activate an option named `Colour`, and an option named `Shade` needs `Shade` in the field.
Swatches show on the product page but not in collections
Two settings have to line up. Enable **Enable color pills** inside the settings of each collection section, then add your option name to **Theme settings → Product card → Color labels**. The Variant label in the Variant selector does not control product cards.
Uploaded PNG files are ignored
Open **Shopify Admin → Content → Files** and compare the stored file name with the option value character for character. The capitalization has to match the option value, spaces have to be underscores, and the extension has to be `.png`.
A color swatch is dimmed / faded
The variant is sold out. Avante shows sold-out variants with reduced opacity so customers can still see the option exists.
A color swatch is missing entirely
The variant combination hasn't been created in Shopify Admin. Avante hides variants that don't exist as valid combinations — not sold-out ones. Go to **Shopify Admin → Products → \[product] → Variants** and make sure all color/size combinations are created.
***
### Related
* [Linked Products](/docs/avante-themes/features-and-advanced-setup/linked-products.md)
* [Display only media related to chosen variant](/docs/avante-themes/features-and-advanced-setup/display-only-media-related-to-chosen-variant.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://staylime.com/docs/avante-themes/features-and-advanced-setup/variant-images-vs-color-swatches.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
| 
|
{% hint style="warning" %}
**If each color is a separate product**, see [Linked Products](/docs/avante-themes/features-and-advanced-setup/linked-products.md) instead — the settings on this page apply to native Shopify variants only.
{% endhint %}
{% hint style="success" %}
**Capitalization doesn't matter.** Avante compares the Variant label with your option name in lowercase, so `Color`, `color` and `COLOR` all match an option named **Color**. Spelling still has to match: `Color` will not match an option named `Colour`.
{% endhint %}
***
### Set up variant images
Variant images show a small thumbnail of the actual product photo for each color option.
