Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 61 ยท Products, Collections and Variants

Metafields in Themes

Read Shopify metafields in a theme: definitions, types, product.metafields.namespace.key, dynamic sources in the theme editor, rich text, references and safe fallbacks.

Products have a title, a price and a description, but real catalogs need more: the fabric of a shirt, the care instructions, an ingredients list, a size chart, a PDF manual. Shopify stores this extra data in metafields: named, typed values attached to a product, variant, collection, page, article, customer, order, shop and more. As a theme developer you do not create the data, merchants do, but you decide where it appears and how it looks.

This lesson covers how a metafield is identified, what the types mean, how to read them in Liquid, how the theme editor connects them to your settings with dynamic sources, and how to degrade gracefully when a value is missing. It follows Building the Product Page, where metafields are the natural place for details that the standard fields do not cover.

Metafields exist only on a real Shopify store, so all theme code below is read-only. The live examples are a small JavaScript stand-in that resolves typed values the way Liquid does conceptually: it is not Shopify's implementation. The Liquid targets current Online Store 2.0 themes; check Shopify's reference for the full list of types, because it grows.

Definitions, namespaces and keys

A metafield value belongs to a resource and is addressed by a namespace and a key. The namespace groups related fields (custom, specs, a vendor name) and the key names the field (material). Together with the owner they identify one value: product.metafields.custom.material.

A metafield definition is the schema a merchant creates in the admin (Settings, Custom data). It fixes the owner type (product, variant, collection...), the namespace and key, a display name, and the type. Definitions matter to you for three reasons:

  • they guarantee every product's custom.material has the same type, so your template can rely on it;
  • the theme editor can only offer a metafield as a dynamic source when a definition exists;
  • they can validate input (a maximum length, an allowed list of choices, a minimum number).

A value can exist without a definition, but then it is untyped from the merchant's point of view and hard to edit. Treat definitions as part of the contract between your theme and the merchant, and document them: "this section expects custom.care_instructions (rich text) on products".

Use a namespace and key that make sense to a merchant, and keep them stable. Renaming a key later silently breaks every template that reads it.

The types you will meet

Type Value you get in Liquid Typical use
single_line_text_field string material, origin
multi_line_text_field string with line breaks short notes
rich_text_field structured rich text care instructions
number_integer, number_decimal number pieces in a set
boolean true or false "Handmade"
date, date_time date string release date
url string link to a guide
color hex string swatch color
money money object deposit amount
rating object with value, scale_max expert score
dimension, volume, weight object with value, unit product size
json parsed JSON structured data
file_reference file or image object PDF manual, extra photo
product_reference, collection_reference, variant_reference, page_reference the referenced resource "pairs with"
metaobject_reference a metaobject entry size chart, see Metaobjects in Themes
list.* an array of the base type several related products

Every base type also has a list version (list.single_line_text_field, list.product_reference), and the value you read is an array you loop over.

Reading a metafield in Liquid

LIQUID
{%- assign material = product.metafields.custom.material -%}
{%- if material != blank -%}
  <p>Material: {{ material.value }}</p>
{%- endif -%}

product.metafields.custom.material is a metafield object. It is nil when the product has no value, which makes the != blank check the standard guard. The useful properties are:

  • .value: the typed value (string, number, boolean, object, array);
  • .type: the type name, such as single_line_text_field;
  • .list?: whether it is a list type.

Output the object directly and Liquid prints a sensible string for simple types, but being explicit with .value is clearer and required for objects. A few examples:

LIQUID
{%- comment -%} number {%- endcomment -%}
{{ product.metafields.custom.pieces.value | plus: 0 }} pieces

{%- comment -%} boolean {%- endcomment -%}
{% if product.metafields.custom.handmade.value %}<span class="badge">Handmade</span>{% endif %}

{%- comment -%} money {%- endcomment -%}
Deposit: {{ product.metafields.custom.deposit.value | money }}

{%- comment -%} dimension {%- endcomment -%}
{%- assign width = product.metafields.specs.width.value -%}
{{ width.value }} {{ width.unit }}

{%- comment -%} product reference {%- endcomment -%}
{%- assign partner = product.metafields.custom.pairs_with.value -%}
{%- if partner -%}<a href="{{ partner.url }}">{{ partner.title }}</a>{%- endif -%}

{%- comment -%} list of products {%- endcomment -%}
{% for related in product.metafields.custom.related.value %}
  {% render 'product-card', product: related %}
{% endfor %}

Rich text and the metafield_tag filter

A rich text metafield is not a plain string. Rendering it as HTML is the job of a filter:

LIQUID
{{ product.metafields.custom.care.value | metafield_tag }}

metafield_tag formats a metafield value according to its type: rich text becomes safe HTML with headings, lists and links; a file reference becomes the right element; dates are formatted. Using it for rich text avoids hand-rolling a converter and keeps the output safe. Its sibling metafield_text returns the value as plain text, handy for a meta description or an aria-label. Check the filter reference for how each type renders before relying on a specific tag.

Files and images

A file_reference value is a file object. For an image you can use the same image filters as for product media; for a generic file, link to its URL:

LIQUID
{%- assign manual = product.metafields.custom.manual.value -%}
{%- if manual -%}
  <a href="{{ manual.url }}" download>Download the manual (PDF)</a>
{%- endif -%}

Always guard before reading properties, as a missing file leaves manual empty.

Dynamic sources in the theme editor

Online Store 2.0 lets merchants connect a section or block setting to a metafield without any code in your Liquid. In the editor, supported settings (text, rich text, image, URL, product, collection and others, depending on type) show a small connect dynamic source button. The merchant picks product.custom.care, and the setting's value now comes from the metafield of whichever product is displayed.

Why this is powerful: one product template, one text block, and every product shows its own content. Why you care as a developer:

  • Your schema stays ordinary. A richtext setting named text works as a static field or as a dynamic one, with no extra code from you.
  • Only settings of a compatible type can connect to a metafield of a matching type. A rich text setting connects to rich text fields, an image setting to file references that hold images.
  • Test with both modes. A section that assumed static text may break when a dynamic source returns empty.
flowchart LR
  A["Metafield definition<br/>custom.care (rich text)"] --> B["Value on each product"]
  C["Theme block setting<br/>type: richtext"] -->|"connect dynamic source"| B
  B --> D["Rendered on the<br/>product page"]
  A -.->|"read directly"| E["Liquid:<br/>product.metafields.custom.care"]
  E --> D

Two routes to the same data: editor-connected settings, or Liquid you write yourself.

Use a dynamic source when the merchant should decide where the value appears. Read the metafield in Liquid when your section needs logic (a table built from a list, a conditional badge, a link to a referenced product).

Fallbacks and empty values

Metafields are optional by nature, so a good section never assumes a value. The patterns:

LIQUID
{%- liquid
  assign origin = product.metafields.custom.origin.value
  if origin == blank
    assign origin = 'Made to order'
  endif
-%}
<p>{{ origin }}</p>
  • Guard each block so an empty one prints nothing, not an empty heading or a dangling "Material:" label.
  • Provide a default only when it is true for every product. Showing "Cotton" for a product that has no data would be misinformation.
  • Remember that false is a legitimate value for booleans, yet Liquid treats false as blank. A "default if blank" pattern would replace a deliberate false, so test booleans with a plain if product.metafields.custom.handmade.value.
  • For lists, use .size or a for ... else block to handle an empty list.

For deeper background on blank versus nil, see Liquid Pitfalls and Debugging.

Stand-in: resolving typed values

Shopify does the resolving for you, so here is a small model to see the idea. It stores values the way a store might (type plus raw value), looks them up by namespace.key, and renders each type to HTML. It also shows a fallback and an unsafe value being escaped.

JS Stand-in: typed metafield resolver

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last three lines show the empty-value story: a missing field is hidden, or replaced by a fallback that you chose on purpose. The tagline's <i> and & come out escaped, which is the behavior you want from untrusted text.

Stand-in: a spec table from a list

Lists are common: a list.single_line_text_field of features, or a list of dimension values. This second stand-in turns a mixed set of metafields into a specification table and skips empty rows, the way a for loop with an if guard would in Liquid.

JS Stand-in: building a spec table with guards

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note the boolean false row ("Dishwasher safe: No") stays. In real Liquid, test booleans with a plain if, and decide deliberately whether "false" should be printed at all.

Practical advice

  • Performance. Reading a few metafields is cheap. Looping over a list of product references and rendering a full card for each adds up, so cap the length with limit. See Liquid Performance for the measuring tools.
  • Translations. Text metafield values can be translated per language through the store's translation tools; the Liquid stays the same. Labels that you write ("Material:") belong in locale files.
  • Access. Liquid can read definitions' values on your storefront. If you also need the same data through the Storefront API, the definition must allow storefront access, covered in Storefront API and Fetching Data from a Theme.
  • Do not store secrets. Anything a theme can print is public.
  • Ownership. Prefer a definition the merchant controls over hard-coding values in a section's schema, so content stays editable without a theme update.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How do you address the metafield with key material in namespace custom on a product?

    Metafields are read through the owner's metafields object, then the namespace, then the key.
  2. 2. What does the metafield_tag filter do for a rich text metafield?

    Rich text is structured data, so metafield_tag formats it according to its type and outputs HTML.
  3. 3. Why is a metafield definition useful to a theme developer?

    A definition fixes owner, namespace, key and type, which gives your template a stable contract and enables editor connections.
  4. 4. A boolean metafield is false. Which statement is correct?

    false is a real value but counts as blank in Liquid, so a default-if-blank pattern would wrongly replace it.
  5. 5. When is a dynamic source in the theme editor the better choice over reading the metafield in Liquid?

    Dynamic sources need no extra code and let merchants place values. Use Liquid when the section needs logic.

Summary

  • A metafield is a typed value on a resource, addressed by namespace and key and described by a definition.
  • Read it as product.metafields.namespace.key, guard against empty, and use .value for the typed result.
  • metafield_tag renders rich text and files safely; reference types give you real resources to link to or render.
  • Dynamic sources connect compatible editor settings to metafields with no extra code.
  • Never assume a value exists: hide empty rows, give defaults only when true for every product, and remember booleans.

Next, learn a more flexible structure for custom content in Metaobjects in Themes.