Skip to main content

Product Siblings (Advanced Setup)

The Product Siblings feature enables you to link related product variants (such as different colors of the same item) across your store using metafields.

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:

SettingDescriptionOptions
Collection for linked productsOptional collection handle to limit scopeLeave blank for all products
Swatch typeVisual display methodImage or Text swatches
Hide variantVariant name to hide on product pagese.g., "Color"
Hide Variant Option

The "Hide variant" option allows you to use the variant for inventory tracking while hiding it from the product page. This is useful when using Product Siblings to handle color selection.

Setting 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"
  • Upload a blue swatch image to product.swatch_image

For the Red shirt:

  • Set product.swatch_color to "Red"
  • Upload a red swatch image to product.swatch_image

For the Green shirt:

  • Set product.swatch_color to "Green"
  • Upload a green swatch image to product.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
  • Keep naming conventions clear and systematic
  • Document your identifier scheme for future reference

Image Quality​

  • For image swatches, use high-quality, consistent swatch images
  • Recommended size: 24px × 24px
  • Use the same background color/style for all swatches
  • Ensure good contrast against the background

Collection Organization​

  • Consider creating a specific collection for linked products to improve performance
  • Limit the collection scope if you have many products
  • Use collection-based filtering when possible

Variant Position​

  • For best results, set the color variant as the third option in your product
  • Keep variant options consistent across related products
  • Test the order to ensure optimal display

Testing​

  • Test the swatches on both desktop and mobile
  • Verify all links work correctly
  • Check loading performance with multiple siblings
  • Ensure hover states work properly

Troubleshooting​

Swatches aren't appearing:

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

Colors not displaying correctly:

  • Check image quality and file format
  • Verify metafield values are correct
  • Ensure consistent lighting in product photos
  • Test on different devices

Performance issues:

  • Limit the number of siblings per product group (6-8 maximum recommended)
  • Optimize swatch images for web
  • Consider using a specific collection to limit scope

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
Developer Note

For advanced customization, developers can modify the swatches display by editing the swatches.liquid snippet and swatches.js file. Always test thoroughly after modifications.

Alternative Setup​

For a simpler, non-metafield approach to product siblings, see the Product Siblings Guide which uses product types, tags, or vendors for grouping.

Last updated on