Shopify Metafields: Display Them in Your Storefront

A metafield is where you put the data your storefront needs that Shopify has no built-in field for — a materials list, a care guide, a size chart, a "handmade in Portugal" badge, a downloadable spec sheet. You define the field once, fill it in per product or collection, and then read it in Liquid wherever it should show. The value lives with the resource, so it stays correct everywhere it is rendered.

This is the hub for the whole topic. It explains what a metafield actually is, the types and namespaces you will meet, how to define one in the admin, and how to output its value in a storefront section — then points to the cluster guides for the exact Liquid syntax, filters, and token patterns.

What a metafield is

A metafield is a typed key/value attached to a Shopify resource. Every metafield has three parts that matter when you go to display it:

• A namespace — a grouping you choose, like custom or specs. It keeps your keys from colliding with Shopify's or an app's.
• A key — the field's name within that namespace, like care_guide or material.
• A type — what kind of data it holds: single_line_text_field, rich_text_field, number_integer, boolean, url, file_reference, list.single_line_text_field, and so on. The type decides how you output the value in Liquid.

Metafields exist on most resources you would want to enrich: products, product variants, collections, pages, blogs, articles, customers, orders, and the shop itself. In Liquid you reach them through a .metafields object, for example product.metafields.custom.material.

Do not confuse metafields with metaobjects. A metafield is a single field on an existing resource. A metaobject is a whole custom record type you define — a "Designer" or "Ingredient" entity with its own fields — that you can then reference from a metafield. Most storefront work starts with plain metafields; reach for metaobjects only when you need a reusable structured entity.

Why display data from a metafield instead of a text setting

When you build a section, you can type content straight into a theme-editor setting. That is fine for one-off copy. But when the same fact belongs to a product — its wash instructions, its warranty length, its country of origin — storing it in a metafield is the better call:

• It stays in sync. The value lives on the product, so every section, template, and page that reads it shows the same thing. Update it once, it changes everywhere.
• It is structured. A number is a number, a boolean is true/false, a file_reference is an actual file. You can format, compare, and loop over it.
• It scales across a catalog. A "Specifications" section written once can render the right specs for all 2,000 products, because each product carries its own metafield values.

That last point is the reason metafields underpin data-driven sections: one piece of Liquid, many products, no copy-pasting. The block that renders it is a normal custom section — metafields just supply its content.

Step 1 — Define the metafield

Before you can read a metafield, it has to exist. In your Shopify admin, go to Settings → Custom data, pick the resource (say Products), and choose Add definition. Give it a name, set the namespace and key (for example custom.care_guide), and pick the type. Save it.

A definition does two useful things: it adds an editing field to that resource's admin page (so merchants fill it in without touching code), and — if you tick Storefronts under access — it exposes the value to Liquid so your theme can read it. Without storefront access, the field holds data but your section cannot render it.

Step 2 — Fill in a value

Open a product (or whichever resource) and scroll to the Metafields area at the bottom of its admin page. Type the value into the field your definition created. For a rich-text field you get a small editor; for a file field you upload or pick a file; for a list you add entries. Save.

Step 3 — Display it in a section

In your section's Liquid, read the metafield through resource.metafields.namespace.key and output it. A referenced metafield object renders its value directly, so for simple text this is enough:

{% if product.metafields.custom.care_guide != blank %}
  <div class="product-care">
    <h3>Care</h3>
    <div class="product-care__body">
      {{ product.metafields.custom.care_guide }}
    </div>
  </div>
{% endif %}

Two habits make this reliable:

• Guard with != blank. Not every product has every metafield filled in. The {% if … != blank %} wrapper means the block only renders when there is something to show — no empty "Care" heading on products without care data.
• Match the type to the output. A rich_text_field renders its HTML through the metafield_tag filter; a list type needs a loop; a file_reference gives you a file object, not a URL. The exact patterns per type are in the guides below.

The step-by-step, with a full section file and schema, is in Display metafields in a section. The filter-and-token reference — metafield_tag, metafield_text, list handling, and how to expose a metafield as a configurable token so merchants pick the field in the editor — is in Metafield tokens and filters.

Keeping a metafield-driven section update-safe

The data in a metafield is safe: it lives on the product, not in your theme, so a theme update never touches it. What a theme update can remove is the section file that renders it. When you add a metafield section by editing theme files, that Liquid becomes part of that theme version — and installing a new version of the theme, or switching themes, publishes a fresh copy of the theme's files and drops your custom .liquid.

So a metafield-driven "Specifications" block can vanish on the next theme update even though the underlying data is untouched. The fix is the same as for any custom section: either keep a disciplined re-apply workflow, or render the section from outside the theme via a Theme App Extension so no update or swap can remove it. SectionGuard takes the second route — its sections read your existing metafields but render from the app, so the block survives every theme change.

Where this goes next

The cluster guides cover the two tasks in depth:

• Display metafields in a section — a complete section that renders product metafields, with the schema and per-type output.
• Metafield tokens and filters — the Liquid filters for each metafield type, and how to let a merchant choose which metafield a section shows.

If your real question is "how do I keep these data-driven sections when I change themes", read Theme App Extensions and the honest comparison alongside this pillar.