How to use Shopify variant metafields (complete guide)

April 13, 2026
Shopify Tips
6 min read
How to use Shopify variant metafields complete guide

Shopify gives you a number of built-in fields for each variant, such as price, SKU, upc, weight, inventory, etc. That’s it, really. If you have variants which differ other than size and colour, this will cause some problems.

Variant metafields solve this. They let you attach any custom data to individual variants: text, numbers, colors, images, URLs, JSON, files. The data is stored in Shopify’s database, accessible in Liquid templates, exposed through the Storefront API, and editable in the product admin. Once you understand how they work, they unlock customization that Shopify’s default fields cannot.

This guide will cover creating definitions, choosing the correct field type, filling field values, displaying field values on the Storefront, performing bulk actions and examples of real world use cases for fields.

In this post

What are variant metafields?

Metafields are additional data that can be stored along with products, collections, customers, orders, and product variants. These extra fields can be tied to specific variants of a product.

Metafields are basically Shopify products/variants extra fields that can hold any type of information you need. These fields act as default shopify product information such as price and SKU, but they can also hold any type of extra field that you might need. This information is then searchable and indexable on the products.

Key points:

  • Each metafield has a namespace and key (like custom.material)
  • Each metafield has a type (text, number, color, image, etc)
  • Values are set per variant, not per product
  • Accessible in Liquid via variant.metafields.namespace.key
  • Accessible through the Storefront API and Admin API

How to create a variant metafield definition

Before you can fill in values, you need a metafield definition. This tells Shopify what kind of data to expect.

  1. Go to Settings > Custom data in your Shopify admin
  2. Click Variants
  3. Click Add definition
  4. Fill in the name (e.g., “Material”), namespace and key (e.g., custom.material), and select a type
  5. Optionally add a description and validation rules
  6. Click Save

The namespace custom is recommended for your own metafields. Apps use their own namespaces (like rubik.variant_images). Never modify metafields in another app’s namespace unless you know exactly what you are doing.

Choosing the right field type

Shopify offers a variety of metafield types to work with, here are 4 that are commonly used for storing variant data.

TypeUse caseExample value
Single-line textShort labels, material names“100% Organic Cotton”
Multi-line textVariant descriptions, care instructions“Machine wash cold…”
Rich textFormatted variant descriptions with bold, listsHTML-like content
Integer / DecimalVariant-specific measurements450 (grams)
ColorCustom swatch hex values#8B4513
URLVariant-specific links (spec sheets, videos)https://example.com/spec.pdf
File referenceVariant-specific images, PDFsA Shopify-hosted file
True/FalseFlags (limited edition, new arrival)true
JSONComplex structured data{“dimensions”: {“width”: 10}}

Most common mistake: Single-line text (plain text) instead of Rich text . If your variant description contains bold text, bullet points or links, it should be set to Rich text. Single-line text will just output plain text without any formatting. Note that Switch later will force you to re-enter all values if you change this.

Filling in metafield values

Once the definition exists, fill in values per variant:

  1. Go to Products and open a product
  2. Scroll to Variants and click a specific variant
  3. Scroll down to the Metafields section in the variant detail panel
  4. Fill in the value for your custom metafield
  5. Save

Not every variant will have a value for the metafield. Variants without a value for the metafield will render as an empty string, which can be handled with a fallback in the rendering section.

Rendering metafields in Liquid templates

Display variant metafields on the product page

{%- assign current_variant = product.selected_or_first_available_variant -%}

<!-- Simple text metafield -->
{%- if current_variant.metafields.custom.material != blank -%}
  <p class="variant-material">
    Material: {{ current_variant.metafields.custom.material }}
  </p>
{%- endif -%}

<!-- Rich text metafield -->
{%- if current_variant.metafields.custom.variant_description != blank -%}
  <div class="variant-description">
    {{ current_variant.metafields.custom.variant_description | metafield_tag }}
  </div>
{%- endif -%}

<!-- Color metafield as swatch -->
{%- if current_variant.metafields.custom.swatch_color != blank -%}
  <span style="background-color: {{ current_variant.metafields.custom.swatch_color }};"
        class="custom-swatch"></span>
{%- endif -%}

Note that | metafield_tag is used for Rich text metafields to transform the stored JSON-like string into proper HTML. Without this filter you would see the raw JSON in your template. For plain text metafield tags you do not need to use this filter.

Swapping metafield content on variant change

Liquid runs on page load. Variant picker change does not cause the page to reload. Metafield content needs to be swapped with JavaScript.

Output all variant metafield values as a JSON object, then swap on change:

<script>
  const variantMeta = {
    {%- for variant in product.variants -%}
      "{{ variant.id }}": {
        "material": {{ variant.metafields.custom.material | default: '' | json }},
        "care": {{ variant.metafields.custom.care_instructions | default: '' | json }}
      }
      {%- unless forloop.last -%},{%- endunless -%}
    {%- endfor -%}
  };
</script>

<script>
  document.addEventListener('change', function(e) {
    const form = e.target.closest('form[action="/cart/add"]');
    if (!form) return;
    const id = form.querySelector('[name="id"]').value;
    const meta = variantMeta[id];
    if (!meta) return;

    const materialEl = document.querySelector('.variant-material');
    if (materialEl) materialEl.textContent = meta.material
      ? 'Material: ' + meta.material : '';
  });
</script>

This works for any metafield type – just add as many fields as necessary to the JSON object. The | json filter will escape the content correctly, and this should then paste correctly into any JavaScript.

Rubik Variant Images uses metafields for variant data on Shopify

Practical use cases

Here are the most common ways stores use variant metafields:

  • Per-variant descriptions. Different materials need different descriptions. Store them in a Rich text metafield and swap them on variant change.
  • Custom swatch colors. Store exact hex values in a Color metafield instead of relying on CSS color name detection. Works with themes like Prestige that read color metafields natively.
  • Care instructions. Leather vs cotton vs polyester all need different wash/care info. A multi-line text metafield per variant covers this.
  • Variant-specific images. While Shopify supports one image per variant natively, Rubik Variant Images uses metafields to store multiple images per variant for gallery filtering. The metafield-based approach means no external API calls and fast loading.
  • Spec sheets. Store a URL or file reference to a variant-specific PDF spec sheet. Display a download link that changes per variant.
  • Lead times. Different variants might have different shipping or production times. An integer metafield like “Ships in X days” per variant sets accurate expectations.

Bulk editing variant metafields

Editing metafields one variant at a time can be exhausting, especially when you have a large product catalog. Here are 3 ways to make it way faster.

  1. Shopify bulk editor. Go to Products, select multiple products, click “Edit products”. The bulk editor shows a spreadsheet-like view where you can add metafield columns and fill in values across variants. Limited but built-in.
  2. CSV import/export. Export your products as CSV, add metafield columns following Shopify’s naming convention (Variant Metafield: custom.material [single_line_text_field]), fill in values in a spreadsheet, and reimport. Good for one-time bulk operations.
  3. Shopify API. For programmatic updates, use the Admin API’s metafields endpoint. Write a script that reads your data source and creates/updates metafields in bulk. Best for ongoing automation.

Variant images metafields can be bulk set for image metafields with 6

For collection-level variant data, the Rubik Combined Listings app uses metafields to store group information and swatch configurations for linked products.

“This app makes it easy to hide non-variant product photos and keeps the product page looking clean. It also helps to show clean custom swatches. Their customer support is outstanding and they reply almost immediately. They were able to fix a bug for me with minimal weight time.”

Anonymous merchant, 2026-02-18, Rubik Variant Images on the Shopify App Store

See the live demo store, watch the setup tutorial, or read the getting started guide.

Try Rubik Variant Images free
Try Rubik Combined Listings free

Frequently asked questions

What is the difference between product metafields and variant metafields?

Metafields can be set up to attach to a product and have the same value for all variants, or to attach to individual variants and have different values per variant. Use product metafields for information such as the brand story or warranty that applies to all product variants. Use variant metafields for information such as material, care instructions, or custom color that may apply differently to different product variants.

Can I display variant metafields without editing theme code?

Partially. Shopify provides a theme customizer that allows you to connect metafields to some custom theme elements (in some blocks you can even use dynamic data sources like files or store variables). It’s possible to do this for the currently selected variant, but you still need to write the JavaScript to swap dynamically on variant change or to use an app to do this for you.

How many metafields can a variant have?

Shopify supports up to 128 definitions of metafields per resource type (in this case variants), and up to one value for each definition per variant. In practice, most stores will never need more than 5 to 10 variant metafields. However, Shopify supports up to 128 metafield definitions per resource type.

Do variant metafields affect page speed?

Metafield values are stored in Shopify as Metafield values and are therefore loaded during the Liquid compilation phase (server-side) and not during API calls. This should have a negligible impact on performance unless you have an excessive amount of metafields. Just be sure to keep your JSON objects of metafield values for the JavaScript swapping reasonable in size because excessively large objects will increase the size of the page also.

Can I import variant metafields via CSV?

Yes. Shopify supports the import of products from a CSV file, and you can include metafields in that file. In the Shopify help, it explains that you can include any metafields in the CSV as long as you use the correct format for the column header. Each variant metafield needs to follow this format: Variant Metafield: namespace.key [type]. For example: Variant Metafield: custom.material [single_line_text_field]. Then you just fill in the values for each row as you import the products.

Do apps like Rubik Variant Images use metafields?

This product allows you to specify different images for the Rubik variant in metafields, instead of trying to store this information in an external database or by making API calls. This product is fast because it is easily integrated and only requires Shopify to load, as the information to be changed is already pre-stored on the site.

You may also like