Local > Metaobject swatch metafields

To display image or color swatches for variant options using metaobjects, follow the steps below:

Step 1: Create a metaobject definition

1. Go to Settings > Metafields and Metaobjects > Metaobject definitions
2. Click Add definition
3. Name it something descriptive (e.g. "Materials list" )
4. Add the following fields:
   • Label → Field type: Single line text (one value)
   • Image → Field type: File (Image) (one value) or
   • Color → Field type: Color (one value)

Step 2: Create metaobject entries

1. Go to Content > Metaobjects and select your definition (e.g. "Materials list" )
2. Create one entry per swatch value. For example:
   • Label: Silk
   • Color: #CC0000 
   • Image: (upload an image)

Step 3: Create a product metafield that references the metaobject

1. Go to Settings > Metafields and Metaobjects > Metafield definitions > Products
2. Click Add definition
3. Configure it as:
   • Name (e.g. Materials list)
   • Enable "List of entries" — this is critical, the feature expects a list
   • Select field type: Metaobject > select your metaobject definition

Step 4: Assign metaobject entries to a product

1. Open a product in the admin area
2. Scroll to the Product metafields section
3. In your new metafield (e.g. custom.materials_list), add the relevant metaobject entries that correspond to this product's variant option values

Step 5: Add variants to the product

1. Add a new product option and select the custom metafield (created in Step 3) from the “Recommended” list. This ensures the option is linked to the product metafield and remains compatible with the swatch rendering logic.

2. The option values will be automatically populated based on the entries defined in the product metafield.

Step 6: Configure the theme

1. Open the Theme Editor
2. Navigate to a Product page
3. Click the Variant picker block from Product page section
4. Make sure the variant picker type is set to "Blocks" — metaobject swatches only work with the blocks, not the dropdown style
5. In the "Metaobject swatch metafields" text field, enter your product metafield reference(s) ( e.g.: custom.materials_list). For multiple metafields (e.g. custom.materials_list and custom.colors), separate them with commas (e.g. custom.materials,custom.colors).

For each variant option value, the theme checks swatches in this priority order:

1. Native Shopify swatch image (from category metafields)
2. Native Shopify swatch color (from category metafields)
3. Metaobject image
4. Metaobject color

If none are found, the option renders as a plain text label with no swatch.