> For the complete documentation index, see [llms.txt](https://docs.strm.design/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.strm.design/products/swatches.md).

# Variants and color swatches

Show colors as swatches on product pages, product cards and filters, and control how each swatch looks.

Stratum shows color options as **swatches** — small circles (or rounded squares) of color or texture — in three places:

* the **variant picker** on product pages and in quick view,
* the **Swatches** block on product cards,
* **color filters** on collection and search pages.

![Swatches on the product page](https://2073252647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX7okZwFVjG38blUMwqg%2Fuploads%2Fgit-blob-41608395d8648894f67ebaae725562773c5fdfd2%2Fvariant-swatches.gif?alt=media)

{% file src="/files/c1sm2S4igbVqkh9DGwlO" %}
Watch the video (MP4)
{% endfile %}

## Which options show swatches

An option shows swatches when **either** of these is true:

1. **It has Shopify swatches.** In Shopify admin you gave the option values a color or an image (see [Add Shopify swatches](#add-shopify-swatches-in-shopify-admin)). These options always show swatches.
2. **Its name is in the list** under **Theme settings › Swatches › Show swatches for options named** (default "Color, Colour") **and every value has a look** (see the next part). Names are matched without regard to capitals.

If one value of a listed option has no look at all, the whole option shows as ordinary buttons instead. That way shoppers never see an empty circle.

{% hint style="info" %}
**Other languages:** add your own words to **Show swatches for options named**, separated by commas — for example `Color, Colour, Màu sắc, Farbe, Couleur`.
{% endhint %}

## How a swatch gets its look

For each value, Stratum uses the first of these that exists:

| Order | Source                                                                               | Example                                      |
| ----- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
| 1     | The **Shopify swatch image** for the value                                           | A photo of the fabric                        |
| 2     | The **Shopify swatch color** for the value                                           | #1f2a44                                      |
| 3     | A line in **Theme settings › Swatches › Swatch colors** with the exact value name    | `Clay: #c27b56`                              |
| 4     | A **common color word** in the name, reading from the end                            | "Army green" → green, "Cosmos Black" → black |
| 5     | The **variant's image**, when **Use the variant image when no color is found** is on | The photo of the clear phone case            |

Common color words Stratum knows include black, white, ivory, cream, beige, sand, natural, oat, stone, grey/gray, graphite, charcoal, silver, steel, chrome, navy, blue, sky, teal, turquoise, green, sage, olive, moss, forest, mint, red, burgundy, pink, blush, rose, purple, lilac, lavender, yellow, mustard, orange, terracotta, clay, rust, copper, bronze, gold, brown, walnut, oak, espresso, tan, khaki, clear and transparent.

## Theme settings › Swatches

Open **Online Store › Themes › Customize**, click the **gear icon (Theme settings)** at the bottom of the left sidebar, then **Swatches**.

| Setting                                          | Default            | What it does                                                                                                                                                                         |
| ------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Show swatches for options named**              | Color, Colour      | Options with these names show swatches even without Shopify swatches. Comma-separated.                                                                                               |
| **Shape**                                        | Circle             | **Circle** or **Rounded square**. Applies to every swatch in the store.                                                                                                              |
| **Swatch colors**                                | Ten example colors | One per line as `Name: color`, for example `Clay: #c27b56`. Used when a value has no Shopify swatch. Also used by color filters. Any CSS color works (`#c27b56`, `rgb(194 123 86)`). |
| **Use the variant image when no color is found** | On                 | Values with no color use their variant's photo as the swatch. Turn off if your variant photos are full product shots that look busy at swatch size.                                  |

{% hint style="warning" %}
**Swatch colors** match the whole value name exactly (capitals don't matter). "Clay" matches `Clay: …`, but "Clay matte" does not — add a separate line for it, or rely on the color word "clay" at the end of the name.
{% endhint %}

## On the product page

![Product page swatches with a tooltip](https://2073252647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX7okZwFVjG38blUMwqg%2Fuploads%2Fgit-blob-a113ec24409623202d23ad1786b31179db54f691%2Fvariant-swatches.png?alt=media)

* The selected value has a dark ring. The ring moves the moment the shopper clicks; the price, photos and stock follow straight after.
* The option heading shows the selected name, for example **Color · Clay**.
* Hovering a swatch on a computer shows its name in a small tooltip.
* **Sold-out values** are dimmed and crossed with a diagonal line. They can still be selected, so shoppers can see the product and use the restock request.
* Options shown as swatches ignore the variant picker's **Style** setting — swatches show even when **Style** is **Dropdown**.

## On product cards

Add a **Swatches** block inside the **Product card** block of any product grid or collection section (it is in the default cards). It shows the product's first swatch option.

![Card swatches](https://2073252647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX7okZwFVjG38blUMwqg%2Fuploads%2Fgit-blob-8091f83a680b299239df7c511daf905482786b47%2Fcard-swatches.gif?alt=media)

{% file src="/files/quoDGcwDPNG3ktrKkqkv" %}
Watch the video (MP4)
{% endfile %}

![A card while hovering a swatch](https://2073252647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX7okZwFVjG38blUMwqg%2Fuploads%2Fgit-blob-a358764b516e71bd94dfb40fba1782b5011348a8%2Fcard-swatches.png?alt=media)

* **Hover** (or focus with the keyboard) a swatch to preview that variant's photo on the card. Moving away puts the photo back.
* **Click or tap** a swatch to select it. The card keeps that photo, and the card's links and **Choose options** quick view open that variant.
* **Space** selects a focused swatch from the keyboard.
* While swatches drive the photo, the card's second-image hover is paused so it can't cover the preview.
* Each swatch has a 24 px tap target and a name tooltip; sold-out values are dimmed and crossed.

| Block setting        | Default  | What it does                                       |
| -------------------- | -------- | -------------------------------------------------- |
| **Maximum swatches** | 6 (3–12) | Extra values show as "+N", linking to the product. |

{% hint style="info" %}
For the photo preview to work, assign an image to each variant in Shopify admin. Values without a variant image still select, but the card photo doesn't change.
{% endhint %}

## In filters

Color filters on collection and search pages also show swatches. This is controlled under **Theme settings › Filters**:

| Setting                   | Default       | What it does                                                                                                                      |
| ------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Color filter names**    | Color, Colour | Filters with these names show as labelled swatches. Filters set to **Swatch** in the Search & Discovery app always show swatches. |
| **Other variant filters** | Buttons       | How other option filters (Size, Material…) look: **Buttons** or **Checkboxes**.                                                   |

Filter swatches use the Shopify swatch first, then **Swatch colors**, then color words in the name. See [Collection pages and filters](/collections-and-search/collection-page.md).

## Add Shopify swatches in Shopify admin

Shopify swatches are the most reliable source because they are attached to the option value itself.

1. In Shopify admin, go to **Products** and open a product.
2. In **Variants**, click the option (for example **Color**) to edit it.
3. If the option uses a **category metafield** (for example "Color" from the product's category), each value can have a swatch: click the value and choose a color or upload an image.
4. Click **Done**, then **Save**.

For colors you use across many products, edit them once in **Content › Metaobjects › Color** (created by Shopify when you use category options), where each entry has a color and an optional image.

## Common questions

**My Color option shows buttons, not swatches.** One of its values has no look. Add a Shopify swatch, add the name to **Swatch colors**, or turn on **Use the variant image when no color is found** and give that variant an image.

**My option isn't called Color.** Add its name to **Show swatches for options named**.

**A swatch shows the wrong color.** Shopify swatches win over everything else; check the value in Shopify admin. Otherwise add an exact line to **Swatch colors**, which wins over color words.