> 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/volume-themes/faq/products-and-variants/how-do-i-link-color-ways-that-are-separate-products.md).

# How do I link color ways that are separate products?

Linking colourways that live as separate products in Volume, using the custom metafields the theme reads.

If each colour of a garment is its own Shopify product, Volume's **Linked products** block puts a row of swatches on the product page that jumps between them.

It is driven entirely by metafields, and the keys are fixed — the theme reads these exact ones and nothing else.

{% stepper %}
{% step %}

### Create one metafield

Under **Settings → Metafields and metaobjects → Products → Add definition**, create **Namespace and key** `custom.linked_products`, type **Product → List of products**.

That is all the block needs. Two more are optional and only change what the swatch looks like: `custom.linked_color` (type **Color**) and `custom.linked_image` (type **File**).
{% endstep %}

{% step %}

### Fill it in on every product in the group

Each product needs its own list pointing at the rest of the group — including itself, so it renders as the selected swatch.

This is the step people skip. If product A lists B and C but B lists nobody, the swatch row disappears the moment a customer lands on B.
{% endstep %}

{% step %}

### Add the block

In **Customize**, open the product template, and inside the **Product overview** section click **Add block → Linked products**. It has an optional **Heading** if you want a label such as “More colours” above the row.
{% endstep %}
{% endstepper %}

### Why the swatches show product photos instead of colours

That is the fallback, not a bug. For each linked product the theme looks for `custom.linked_image` first, then `custom.linked_color`, and if neither is filled it falls back to that product's **featured image**. So a group with no colour or image metafields still works — it just shows cropped photos.

Fill `custom.linked_color` on every product in the group to get solid chips instead. If both metafields are filled on the same product, the image wins.

### Why the swatches show on the product page but not on collection cards

Two separate switches control the card version, and both have to be on:

* **Theme settings → Product card → Pills** must be **Linked products** or **Both**. The default is **Variants**, which shows variant swatches only.
* In the section holding the cards, **Desktop product options and linked products** and **Mobile product options and linked products** must be **Enable** (or **Enable on hover**) rather than **Disable**.

{% hint style="success" icon="lightbulb" %}
Styling for the row lives in **Theme settings → Variant picker → Linked products**: **Size**, **Mobile size**, **Media ratio**, **Focal point** and **Corner radius**. These apply to the product page and the collection cards alike.
{% endhint %}

{% hint style="success" icon="lightbulb" %}
Full walkthrough, including swatch ordering and the `custom.custom.` naming trap, in [Linked Products](/docs/volume-themes/products/linked-products.md). If your colours are variants of one product rather than separate products, use [Color Swatches](/docs/volume-themes/products/color-swatches.md) instead.
{% endhint %}


---

# 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/volume-themes/faq/products-and-variants/how-do-i-link-color-ways-that-are-separate-products.md?ask=<question>&goal=<user_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.