Linked Products

Set up linked products for related variants or 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

Linked Products vs Variant Images: If your colors exist as variants within a single product, see Variant images vs Color Swatches 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.

---

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

---

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

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.

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.

---

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

---

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

---

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

If both custom.linked_color and custom.linked_image are filled in, the image takes priority.

---

The Show only media of selected variant setting (from Display only media related to chosen variant) 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.

---

Common issues

Swatches are not showing on the product page

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)

Swatches appear in the wrong order

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.

I see product photos instead of colors

Create the custom.linked_color metafield (see "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.

---

Related

• Variant images vs Color Swatches — for colors set up as variants within one product
• Display only media related to chosen variant — filter product gallery by selected variant

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.