> 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

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  | <p></p><p><img src="/files/5zR9RlVmUcRHlAxf2rxk" alt="" data-size="original"></p> | <p></p><p><img src="/files/NMlE9LFxP9zOzNBrk9uS" alt="" data-size="original"></p> |

{% 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="warning" %}
**Variant label must match your product option name exactly — including capitalization.** If your option is named `Colour` or `Color`, the Variant label field must match it character for character. `color` ≠ `Color` ≠ `Colour`.
{% endhint %}

***

### Set up variant images

Variant images show a small thumbnail of the actual product photo for each color option.

<figure><img src="/files/NMevV55bnN9roQXTHrRb" alt=""><figcaption></figcaption></figure>

{% 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 %}

<figure><img src="/files/PPN0s25WxvwM1nbfoYih" alt=""><figcaption></figcaption></figure>

***

### Set up color swatches

Color swatches show a small color circle instead of a product photo.

<figure><img src="/files/VFEmLZhm93qj8fU0Jvwl" alt=""><figcaption></figcaption></figure>

{% 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 %}

<figure><img src="/files/g91jSDjUDHvD117EvIAk" alt=""><figcaption></figcaption></figure>

#### Enable swatches on collection cards

By default, swatches appear on the product page only. To show them on product cards in collections:

Go to **Theme Editor → \[your collection section] → section settings** and enable **Enable color pills**.

This setting is available in Featured collection, Collection page, and similar sections individually.

***

### Set up custom color swatches

Avante uses standard HTML color names by default. If a color name doesn't match, or the displayed shade looks wrong, you can customize 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**

<figure><img src="/files/OvMSsivRSA3RuXUL2rnX" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Prepare the image files

Create **PNG** files for your color values. Name each file to **match the variant** value. Use lowercase letters and underscores for spaces.

* `Red` → `red.png`
* `Ocean blue` → `ocean_blue.png`

Recommended: **60×60px**, under **20KB**

<figure><img src="/files/AWlJ2SYNzsrDsilqMncF" alt=""><figcaption></figcaption></figure>
{% 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 automatically links the images to matching color variants across your store.

{% hint style="info" %}
Custom swatches only work when the file name matches the variant value format.
{% 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 %}

<figure><img src="/files/3KQ3snoBDRj987wa85vZ" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Use PNG files when you need textures, patterns, or photographic swatches. For solid colors, the Configuration field is quicker.
{% endhint %}

***

### Common issues

<details>

<summary><strong>Swatches are not showing at all</strong></summary>

Check that the value in **Variant label** matches your product option name exactly, including capitalization. `Color` ≠ `color` ≠ `Colour`.

</details>

<details>

<summary><strong>Swatches show on the product page but not in collections</strong></summary>

Enable **Enable color pills** inside the settings of each collection section (Featured collection, Collection page, etc.).

</details>

<details>

<summary><strong>A color swatch is dimmed / faded</strong></summary>

The variant is sold out. Avante shows sold-out variants with reduced opacity so customers can still see the option exists.

</details>

<details>

<summary><strong>A color swatch is missing entirely</strong></summary>

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.

</details>

***

### 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://staylime.com/docs/avante-themes/features-and-advanced-setup/variant-images-vs-color-swatches.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.