Ctrlk
Contact support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Linked Products

Connect separate products and display them as clickable color swatches on the product page. Each color gets its own product card on Collection pages.

Some merchants choose to set up each color as a separate product instead of using Shopify variants — for example, to show individual product cards per color on Collection pages or to keep product galleries clean. Linked Products connects these separate products and displays them as switchable swatches on the product page.

sparkles

Note: If your colors exist as variants within a single product, Linked Products is not the right feature for you. 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.

1

Step 1 — Create the metafield

  1. Go to Shopify Admin → Settings → Metafields and metaobjects → Products

  2. Click Add definition

  3. Fill in the fields:

    • Name: Linked products (this is just a visible label — can be in any language)

    • Namespace and key: custom.linked_products

    • Type: Product — List of products

  4. Save

The Namespace and key field is what matters. Make sure custom.linked_products goes into the Namespace and key field — not the Name field. The Name field is just a visible label and can be anything. If you type custom.linked_products into the Name field by mistake, Shopify will add its own custom. prefix on top, resulting in custom.custom.linked_products — and the theme won't recognize it.

2

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.

3

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

4

Step 4 — Adjust the design

  1. In Theme Editor go to Theme settings → Variant picker

  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×100 px) for each product

sparkles

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

Troubleshooting

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 Namespace and key is exactly custom.linked_products — not custom.custom.linked_products or anything else. Go to Settings → Metafields and metaobjects → Products, click your definition, and verify the value under "Namespace and key"

  • The metafield 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

  • Size Guide — how to set up a size chart using metafields

  • Smart Category Menu — another way to organize products on Collection pages

Last updated

Was this helpful?