> 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/linked-products.md).

# Linked Products

Linked Products let you connect separate products and display them as color swatches on the product page. This is useful when you want to:

* Show each color as a separate product on Collection pages
* Display only the images of the selected color in the product gallery

{% hint style="warning" %}
**Linked Products vs Variant Images:** If your colors exist as variants within a single product, see [Variant images vs Color Swatches](/docs/avante-themes/features-and-advanced-setup/variant-images-vs-color-swatches.md) instead. Linked Products requires each color to be a separate product in your catalog — this is a significant catalog restructuring, so consider it before getting started.
{% endhint %}

***

### Step 1 — Create the metafield

1. Go to **Shopify Admin → Settings → Metafields and metaobjects → Products**
2. Click **Add definition**
3. Fill in the fields exactly as shown:
   * **Name:** `Linked products`
   * **Namespace and key:** `custom.linked_products`
   * **Type:** Product — List of products
4. Save

<figure><img src="/files/0DhSUXDRPe6u97y56Xwz" alt=""><figcaption></figcaption></figure>

***

### Step 2 — Link products together

1. Go to **Shopify Admin → Products → \[your product]**
2. Scroll down to **Product metafields**
3. Find **Linked products** and select all the products in the same color group
4. **Include the current product itself** — this makes it appear first and look selected when a customer views that product
5. Save

{% hint style="warning" icon="triangle-exclamation" %}
Each product in the group must have the metafield filled in — including the current product itself. If any product is missing it, its swatch won't appear on the other products' pages.
{% endhint %}

#### Swatch order

Order is set by drag-and-drop directly inside the metafield on the product page — not in the Variants section. The order must be set manually in each product of the group. If you skip this, swatches will appear in a different order on different product pages.

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

***

### Step 3 — Add the block in Theme Editor

1. Go to **Theme Editor → Products → Default product template**
2. Inside the **Product overview** section click **Add block → Linked products**
3. Save

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

***

### Step 4 — Adjust the design

1. In Theme Editor go to **Theme settings → Variant selector**
2. Scroll down to **Linked products**
3. Adjust **Image ratio**, **Focal point**, **Corner radius** and **Shadow** to match your store design

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

***

### Optional: Use color swatches instead of product images

By default, each swatch shows the first image of the linked product. You can replace it with a solid color or a custom image (useful for textures like wood grain, marble, etc.).

#### **Option A — Solid color swatch**

1. Go to **Shopify Admin → Settings → Metafields and metaobjects → Products**
2. Click **Add definition** and create a new metafield:
   * **Name:** `Linked color`
   * **Namespace and key:** `custom.linked_color`
   * **Type:** Color
3. Save
4. Open each product, scroll to **Metafields**, and pick the color

The theme will automatically replace the product image with this color in the Linked Products block.

#### **Option B — Custom image swatch**

1. Create a metafield with these settings:
   * **Name:** `Linked image`
   * **Namespace and key:** `custom.linked_image`
   * **Type:** File
2. Upload a small square image (PNG, \~100×100px) for each product

{% hint style="warning" %}
If both `custom.linked_color` and `custom.linked_image` are filled in, the image takes priority.
{% endhint %}

***

{% hint style="warning" %}
The **Show only media of selected variant** setting (from [Display only media related to chosen variant](/docs/avante-themes/features-and-advanced-setup/display-only-media-related-to-chosen-variant.md)) does not apply to Linked Products. Since each color is a separate product with its own gallery, media filtering happens automatically — each product page already shows only its own images.
{% endhint %}

***

### Common issues

<details>

<summary><strong>Swatches are not showing on the product page</strong></summary>

Check that:

* The **Linked products** block is added inside the Product overview section in Theme Editor
* The metafield `custom.linked_products` is filled in on the product you're viewing — including the product itself
* Every product in the group has the metafield filled in (not just one of them)

</details>

<details>

<summary><strong>Swatches appear in the wrong order</strong></summary>

The order follows the sequence of products in the metafield. Go to **Shopify Admin → Products → \[your product] → Metafields → Linked products** and drag the items into the desired order.

Remember to update the order on **every product in the group** — each product has its own independent list.

</details>

<details>

<summary><strong>I see product photos instead of colors</strong></summary>

Create the `custom.linked_color` metafield (see "[Optional: Use color swatches instead of product images](#optional-use-color-swatches-instead-of-product-images)" above) and assign a color to each product. Without this metafield, the theme defaults to showing the first product image.

</details>

***

### Related

* [Variant images vs Color Swatches](/docs/avante-themes/features-and-advanced-setup/variant-images-vs-color-swatches.md) — for colors set up as variants within one product
* [Display only media related to chosen variant](/docs/avante-themes/features-and-advanced-setup/display-only-media-related-to-chosen-variant.md) — filter product gallery by selected variant

{% hint style="danger" icon="octagon-exclamation" %}
Linked Products requires each color to be a **separate product** in your catalog. If your colors currently exist as variants within one product, you will need to create individual products for each color first. This is a significant catalog restructuring — consider this before getting started.
{% 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 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/linked-products.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.