How to Display Images Using Metafields in Shopify

Shopify metafields allow you to store and display custom data - including images - on your storefront without relying on third-party apps. Since the launch of Online Store 2.0, Shopify has provided built-in metafield support that makes it straightforward to add extra product images, size guides, collection banners, ingredient lists, and other custom visual content to any page. This step-by-step guide shows you how to create metafield definitions, upload images, and display them in your Shopify theme using both the no-code theme editor and Liquid template code.

What Are Shopify Metafields?

Metafields are custom data fields that extend Shopify's default data model. Every resource in Shopify - products, variants, collections, customers, orders, pages - has a set of standard fields (title, description, price, etc.). When you need to store additional information that does not fit into these standard fields, you use metafields.

Metafields support multiple data types: single-line text, multi-line text, integers, decimals, dates, booleans, URLs, colors, dimensions, weights, JSON, references to other resources, and - most relevant to this guide - file references including images. Each metafield has a namespace, a key, and a value. The namespace groups related metafields together, while the key identifies the specific field.

Step 1: Create a Metafield Definition

Before adding image data, you need to define the metafield in your Shopify admin:

Go to Settings → Custom data in your Shopify admin
Select the resource type you want to add the metafield to (e.g., Products, Collections, Pages)
Click Add definition
Enter a Name (e.g., "Size Guide Image" or "Gallery Image")
The Namespace and key will be auto-generated (e.g., custom.size_guide_image)
For the Type, select File (this allows image uploads)
Optionally add a description and validation rules
Click Save

For multiple images (a gallery), choose the List of files type instead of single File. This allows you to upload multiple images to a single metafield.

Step 2: Add Images to the Metafield

Once the metafield definition exists, you can add images to individual products (or whichever resource you chose):

Go to Products and open a product
Scroll down to the Metafields section
Find your newly created metafield (e.g., "Size Guide Image")
Click to upload an image file (JPG, PNG, WebP, SVG, or GIF)
Save the product

The image is now stored in the metafield and can be displayed on your storefront.

Step 3: Display Metafield Images - No-Code Method (Theme Editor)

If your theme supports Online Store 2.0 (most modern themes do), you can display metafield images without writing any code:

Go to Online Store → Themes → Customize
Navigate to the template where you want to show the image (e.g., the product page template)
Add an Image section or block
Instead of uploading a static image, click the Dynamic source icon (looks like a database icon)
Select the metafield you created (e.g., product.metafields.custom.size_guide_image)
The image will now dynamically pull from each product's metafield data
Save the theme

This is the fastest way to display metafield images and requires zero coding knowledge. The image automatically changes based on which product the customer is viewing.

Step 4: Display Metafield Images - Liquid Code Method

For more control over how metafield images are rendered, you can use Liquid code directly in your theme templates:

Basic Image Display

{% if product.metafields.custom.size_guide_image %}
  {{ product.metafields.custom.size_guide_image.value
     | image_url: width: 800
     | image_tag: alt: "Size guide", loading: "lazy", class: "metafield-image" }}
{% endif %}

This code checks if the metafield has a value, generates an optimised image URL at 800px width, and renders it as an <img> tag with alt text and lazy loading.

Responsive Images with srcset

{% if product.metafields.custom.size_guide_image %}
  {% assign image = product.metafields.custom.size_guide_image.value %}
  <img
    src="{{ image | image_url: width: 800 }}"
    srcset="
      {{ image | image_url: width: 400 }} 400w,
      {{ image | image_url: width: 800 }} 800w,
      {{ image | image_url: width: 1200 }} 1200w"
    sizes="(max-width: 768px) 100vw, 50vw"
    alt="Size guide for {{ product.title }}"
    loading="lazy"
    width="{{ image.width }}"
    height="{{ image.height }}"
  >
{% endif %}

This provides responsive images that load the appropriate size based on the customer's viewport, improving performance and Core Web Vitals scores.

Displaying Multiple Metafield Images (Gallery)

{% if product.metafields.custom.gallery_images.value %}
  <div class="metafield-gallery">
    {% for image in product.metafields.custom.gallery_images.value %}
      {{ image | image_url: width: 600
         | image_tag: alt: product.title, loading: "lazy" }}
    {% endfor %}
  </div>
{% endif %}

Common Use Cases for Metafield Images

Size guides: Different size chart images per product category
Ingredient or material images: Visual representations of materials or ingredients
Collection banners: Custom hero images for each collection page
Certification badges: Product-specific certifications (organic, fair trade, etc.)
How-to images: Assembly instructions or usage guides specific to each product
Lifestyle galleries: Additional lifestyle or context images beyond the main product photos
Brand logos: Vendor or brand logos displayed alongside products

Metafield Image Optimisation Tips

Always use the image_url filter with a width parameter - this generates optimised, CDN-hosted images rather than serving full-resolution originals
Add loading: "lazy" to metafield images that appear below the fold to improve page speed
Include width and height attributes to prevent Cumulative Layout Shift (CLS)
Use WebP format where possible for smaller file sizes
Write descriptive alt text for accessibility and SEO

Troubleshooting Common Issues

Metafield Image Not Displaying

If your metafield image is not showing, check that the metafield definition is set to the File type (not URL or text), the product actually has an image uploaded to that metafield, you are referencing the correct namespace and key in your Liquid code, and the image file format is supported (JPG, PNG, WebP, SVG, GIF).

Dynamic Source Not Available in Theme Editor

If you do not see the dynamic source icon in the theme editor, your theme may not support Online Store 2.0. Check if your theme has a .json templates folder - if it uses .liquid templates instead, it is a vintage theme that does not support dynamic sources. Consider upgrading to an OS 2.0 theme.

Need Help with Shopify Metafields?

If you need help setting up metafields, customising your theme to display metafield data, or building more complex metafield-driven features, our Shopify theme development services can help. As a certified Shopify Partner, DigiXoft specialises in custom Shopify development including metafield implementations, Online Store 2.0 theme builds, and performance optimisation.

Frequently Asked Questions About Shopify Metafields

What are Shopify metafields?

Shopify metafields are custom data fields that let you store additional information beyond Shopify's standard fields. They can hold text, numbers, dates, files (including images), and references to other resources. Metafields can be attached to products, variants, collections, customers, orders, pages, and other Shopify resources.

How do I display a metafield image in my Shopify theme?

There are two methods. The no-code method: in the theme editor, add an Image block, click the dynamic source icon, and select your metafield. The code method: in your Liquid template, use {{ product.metafields.custom.your_field.value | image_url: width: 800 | image_tag }}. Both methods work with Online Store 2.0 themes.

Can I use metafields without coding in Shopify?

Yes. With Online Store 2.0 themes, you can connect metafield images (and other metafield types) directly to section blocks in the theme editor using the dynamic source feature. This no-code approach lets you display metafield data without editing any Liquid template files. You just need to create the metafield definition in Settings → Custom data and add the data to your products.

How many metafields can a product have?

Shopify allows up to 250 metafield definitions per resource type. Each individual product can have values for all 250 defined metafields. In practice, most stores use 5-20 custom metafields per product type. There is no practical limit for most use cases.