Skip to main content

Product Siblings

Overview​

The Product Siblings feature enables you to link related product variants (such as different colors of the same item) across your store. This creates a seamless shopping experience by displaying color swatches on product cards and product pages, allowing customers to easily switch between related products.

How It Works​

The feature uses metafields to establish relationships between products that are variants of the same base item. When enabled, customers can click on color swatches to navigate between different variants (e.g., a shirt in different colors).

Setup Instructions​

1. Enable Product Siblings Feature​

  • Go to your Shopify admin dashboard
  • Navigate to Online Store > Themes
  • Click Customize on your current theme
  • Go to Theme Settings > Product siblings
  • Check the box next to Product siblings to enable the feature

2. Configure Swatch Settings​

While in the Product Siblings settings:

  • Collection for linked products: Optionally enter a collection handle to limit which products are included in sibling relationships. Leave blank to search all products.
  • Swatch type: Choose between Image (visual color swatches) or Text (text-based color names).
  • Hide variant: Enter the variant name (e.g., "Color") that should be hidden on product pages. This option allows you to use the variant for inventory tracking while hiding it from the product page.

3. Set Up Product Metafields​

For each product that should be part of a sibling group, you need to add the following metafields:

Required Metafields:​

swatch.product_identifier

  • Namespace: swatch
  • Key: product_identifier
  • Value: A unique identifier that groups related products (e.g., "blue-t-shirt-collection")
  • Type: Single line text

product.swatch_color

  • Namespace: product
  • Key: swatch_color
  • Value: The color name (e.g., "Blue", "Red", "Green")
  • Type: Single line text

product.swatch_image (required for image swatches)

  • Namespace: product
  • Key: swatch_image
  • Value: Upload an image or reference a file
  • Type: File reference

Setting Up Metafields:​

  1. Go to Shopify admin > Settings > Custom data
  2. Create the metafield definitions if they don't exist
  3. Navigate to a product you want to include
  4. Scroll down to the Metafields section
  5. Add the required metafields with appropriate values
  6. Repeat for all related products, ensuring they share the same swatch.product_identifier value

Example Setup​

Let's say you have a t-shirt available in Blue, Red, and Green:

  • For all three products, set swatch.product_identifier to "basic-tshirt-collection"
  • For the Blue shirt, set product.swatch_color to "Blue" and upload a blue swatch image
  • For the Red shirt, set product.swatch_color to "Red" and upload a red swatch image
  • For the Green shirt, set product.swatch_color to "Green" and upload a green swatch image

How It Displays​

When properly configured:

  • Product Cards: Show color swatches below the product image
  • Product Pages: Show color swatches that link to other color variants
  • Active State: The current product's swatch is highlighted
  • Hover: Hovering over a swatch shows it as active
  • Click: Clicking a swatch navigates to that product variant

Best Practices​

  • Consistent Naming: Use the same product_identifier format across related products
  • Image Quality: For image swatches, use high-quality, consistent swatch images (24px × 24px recommended)
  • Collection Organization: Consider creating a specific collection for linked products to improve performance
  • Variant Position: For best results, set the color variant as the third option in your product
  • Testing: Test the swatches on both desktop and mobile to ensure they display correctly

Troubleshooting​

If swatches aren't appearing:

  • Verify that the Product Siblings feature is enabled in theme settings
  • Check that all required metafields are correctly set up for each product
  • Ensure products share the exact same swatch.product_identifier value
  • For image swatches, confirm that swatch images are properly uploaded
  • Clear your browser cache and refresh the page

Technical Details​

The Product Siblings feature utilizes:

  • SwatchStore: A JavaScript module that maintains relationships between products
  • Metafields: Custom data fields that store product relationship information
  • Liquid Templates: Templates that render swatches based on metafield data
  • AJAX Compatibility: Works with filtering, sorting, and pagination operations

For advanced customization, developers can modify the swatches display by editing the swatches.liquid snippet and swatches.js file.