> For the complete documentation index, see [llms.txt](https://docs.optis.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optis.me/swatch/variant-display/custom-swatch.md).

# Custom swatch

{% hint style="success" %}
**Available on:** Product page, Collection page
{% endhint %}

✨Demo product: [Custom swatch](https://optis-color-swatch-variant.myshopify.com/products/custom-swatch?pr_prod_strat=collection_fallback\&pr_rec_id=a9de6891c\&pr_rec_pid=8274609307785\&pr_ref_pid=8274596233353\&pr_seq=uniform) (password: 1)

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FhWVxJabQxusTWj1LWsEZ%2Fimage.png?alt=media&amp;token=84690720-9e44-4df5-a7fc-c41bbc917086" alt=""><figcaption></figcaption></figure>

### **Function**

**Custom swatch** lets you manually decide what each variant value looks like, instead of relying on the product images. For every value you can set a **common** swatch — shared by every product that has that value — as:

* An **uploaded image** — a pattern, texture, fabric close-up, or any picture you choose, or
* A **solid color** entered as a **hex code**, or
* Or a **two-color split** — two hex codes shown side by side in the same swatch (great for values like *Black / White*).

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FDqJNsM3OuVsYwHkLraHT%2Fimage.png?alt=media&amp;token=4f695e2b-de4b-4b43-bc21-29cf7a1f0985" alt=""><figcaption></figcaption></figure>

Each value is independent, so you can mix images and colors within the same option. If a couple of products need a different shade under the same value name (e.g. two products both have a "Pink" variant, but the real color isn't quite the same), you can also override the swatch for just those products — see below.

### **Use when**

* Variants already have images in Shopify **but you don’t want to use those images as swatches**.
* You want swatches to show **patterns, textures, materials, or plain colors** rather than full product photos.
* A value has **no variant image**, so [Auto image swatch](https://docs.optis.me/swatch/variant-display/auto-image-swatch.md) has nothing to show.
* You need **precise brand colors** that a photo can’t reproduce accurately.

### **Custom swatch vs. Auto image swatch**

<table><thead><tr><th width="363.62890625">Custom swatch</th><th>Auto image swatch</th></tr></thead><tbody><tr><td>You set the image/color for each value by hand</td><td>Uses the variant images already in Shopify</td></tr><tr><td>Supports solid colors, two-color split, and uploaded images</td><td>Shows the product photo only</td></tr><tr><td>Best for colors, patterns, and textures</td><td>Best when variant photos already look good as swatches</td></tr></tbody></table>

***

## How to use Custom swatch

{% stepper %}
{% step %}

#### Change the display type to Custom swatch → Click Save

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FzNYb6825TXSE6gtvVfFt%2FScreenshot%20(14).png?alt=media&amp;token=9ac51d8e-dfed-4804-ab17-b1159f20c984" alt=""><figcaption></figcaption></figure>

In **Variants display**, find the option you want to configure and set its **Product page display** (and/or **Collection page display**) to **Custom swatch**.

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FmDw3FIKyY5o8l8mVUPbG%2FScreenshot%20(15).png?alt=media&amp;token=5697fa3b-94c1-4763-bb5a-cdac42269d17" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Open the swatch editor (pencil icon)

Once the display type is **Custom swatch**, a **pencil / edit icon** appears next to it. Click it to open the editor — titled **Custom Swatch:&#x20;*****{option name}*** — which lists every value of that option. Click **"Show N products"** under a value to expand the individual products using it.

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2Fgit-blob-428cc38f8e05adf5700ee767caf4691b284de44f%2Fcustom-swatch-change-display-type.png?alt=media" alt="Changing the display type to Custom swatch"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Assign a swatch to each value — or override it for one product

Each value row, and each product row under it, has the same three ways to set a swatch:

* **Add color (1st color)** — click the first color box and pick a color or paste a **hex code** (e.g. `#FF0000`).
* **Add a 2nd color** — pick a second color to create a **two-color split** swatch. The direction of the split (diagonal, horizontal, vertical) is controlled globally in [Two-color swatch split](https://docs.optis.me/swatch/global-settings/two-color-swatch-split.md).
* **Upload image** — upload your own picture (pattern, texture, fabric detail, etc.) to use as the swatch.

Set it on the **value row** and it becomes the **common** swatch for every product with that value. Set it on a **product row** instead (after expanding "Show N products") and only that product uses it — the product now overrides the common swatch; enter the same value as the common swatch again, or click **Reset** on that row, to go back to using the common swatch.

The **thumbnail on the left updates live**: it shows the common swatch, or a stacked preview once at least one product has its own override.

{% hint style="info" %}
A value (or a product's override) can be **either a color or an image**, not both. Setting a color clears an uploaded image, and uploading an image clears the colors — the editor switches automatically.
{% endhint %}

{% hint style="warning" %}
Setting a different swatch per product is a **paid-plan feature**. Shops on a legacy free plan, or a free plan past the 72‑hour trial, see the per-product fields locked with an **Upgrade** link — see [Pricing Plans](https://docs.optis.me/swatch/subscription-and-billing/pricing-plans.md). Product-specific swatches set before being downgraded are kept and reappear once the shop is back on a paid plan.
{% endhint %}

To clear swatches in bulk, tick the rows you want (ticking a value selects its common row **and** every product under it) and click **"Remove swatch"**.
{% endstep %}

{% step %}

#### (Optional) Save time with Auto-assign & Bulk update

At the bottom of the editor you’ll find two helpers:

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FHrD9btJVdnu1WPPlRRU0%2Fimage.png?alt=media&amp;token=adc70419-df9b-4f41-a22f-11aad89b2317" alt=""><figcaption></figcaption></figure>

* **✨ Auto-assign swatch** — fills in a matching **common** color for every value that doesn't have one yet, in one click (from the Color taxonomy metafield, the value name, or the variant image); it never overwrites a product's own override. See [Auto-assign swatch](https://docs.optis.me/swatch/variant-display/auto-assign-color-swatch.md).
* **Bulk update** — **Import** a `.csv` / `.xlsx` file to set many swatches at once, or **Export** your current values to edit them in a spreadsheet. The file has an `Apply_to` column so each row can target **All products** (the common swatch) or one **Specific product** (an override).

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FcpD8kKyZ2ow4RZjxpQnF%2Fimage.png?alt=media&amp;token=686b0b85-9e5c-4581-8210-89b439b6f6d6" alt=""><figcaption></figcaption></figure>

Use the **Search variant** box at the top to quickly find a value when an option has many of them.

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FejeSgobvwMqdlfcSmeVx%2Fimage.png?alt=media&amp;token=2c7e6243-9269-4bc4-a5ec-0ecdddd15fd3" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Click Save to apply changes

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FtyIyw4L6D73AZ8n5AyqG%2Fimage.png?alt=media&amp;token=ed73441f-052d-4415-9032-475339646f68" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**A 2nd color needs a 1st color.** If you set only the second color of a value, the editor shows an error and **Save is disabled** until you also set the first color (or clear the second one).
{% endhint %}

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2Fqhdphb2PKFl6TpHaAXzL%2Fimage.png?alt=media&amp;token=d99e6bdd-a891-4815-bbaa-d192e7e33829" alt=""><figcaption></figcaption></figure>

***

## How it looks on your store

* **Product page:**

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2Fgit-blob-cbbcb63ad02a19af5caa62b0bc78bdf61f34f960%2Fcustom-swatch-product-page.png?alt=media" alt="Custom swatch on the product page"><figcaption></figcaption></figure>

* **Collection page:**

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2Fgit-blob-b2c137a180532c16dcb7ce0766633cb052c49985%2Fcustom-swatch-collection-page.png?alt=media" alt="Custom swatch on the collection page"><figcaption></figcaption></figure>

{% hint style="info" %}
Want to change the **size, shape, spacing, or border** of the swatches? That’s handled separately in [Styling](https://docs.optis.me/swatch/styling/styling-overview.md), not in the Custom swatch editor.
{% endhint %}

<figure><img src="https://4026661835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F50cmOdvfYj3qqQaTzKEI%2Fuploads%2FIjbne3KcEc7mJ2NBm1mc%2Fimage.png?alt=media&amp;token=f7a8d06b-acf2-42f8-9ca8-4f00c6f309e9" alt=""><figcaption></figcaption></figure>

### Related

* [🖼️ Auto image swatch](https://docs.optis.me/swatch/variant-display/auto-image-swatch.md) — use variant images automatically
* [🪄 Auto-assign swatch](https://docs.optis.me/swatch/variant-display/auto-assign-color-swatch.md) — fill colors in one click
* [Two-color swatch split](https://docs.optis.me/swatch/global-settings/two-color-swatch-split.md) — control the split direction
