Shopify Product Metafield — Clean Liquid Render Pattern

Metafields are key-value data attached to Shopify resources — products, variants, collections, customers, orders. Every metafield lives in a namespace (a group identifier) and has a key (the field name within that group). The custom namespace is reserved for metafields you create in Shopify admin — it’s the most common namespace. Third-party apps create their own namespaces (e.g., seo.hidden for SEO data). Access syntax is resource.metafields.namespace.key. Inside the Liquid context, a metafield is a Metafield object — not a string, not a number — with properties like .value, .type, and .unit (for measurements). Understanding this object shape is the key difference between “just output the value” and “render the right HTML for each type.”

Liquid’s truthiness system treats all of these as blank: nil (metafield doesn’t exist), an empty string "" (metafield exists but has no value), an empty array [], and the boolean false. The {% if metafield != blank %} guard catches all of them in one comparison. This is more robust than checking {% if metafield %} alone, because Liquid’s implicit truthiness can be surprising — a string "false" is truthy, a metafield object wrapping an empty string might evaluate differently depending on the Shopify API version. Explicitly comparing to blank is the idiomatic Shopify pattern. Without this guard, rendering a nonexistent metafield throws a Liquid error: undefined method that breaks the entire page — not just the metafield, the whole template stops rendering at that line.

Snippet parameters pass data from the calling template into the reusable file. The {% render 'metafield', metafield: value, type: 'text' %} syntax creates named variables that exist only inside the rendered snippet — they don’t pollute or collide with the parent template’s variables. This is called snippet scoping. The with keyword (old syntax: {% render 'name' with variable %}) sets a single parameter accessible inside the snippet as the snippet’s basename — e.g., inside snippets/metafield.liquid, with sets {{ metafield }}. The newer named-parameter syntax (metafield: value) is preferred for multiple parameters and clearer intent. Step 4 uses with for simplicity; Step 5 upgrades to named parameters for the production version.

Each metafield type produces a different HTML structure because the underlying data has a different shape. Single line text (single_line_text_field): the metafield object stringifies directly to the text value — use {{ mf }} or {{ mf | escape }}. Multi-line text (multi_line_text_field): same stringification, but newlines are lost unless you apply | newline_to_br to convert n into <br> tags. File reference / image (file_reference): the metafield resolves to a Shopify file object — stringifying gives a CDN path, but to actually render an image you need {{ mf | image_url }} which produces a full CDN URL with the correct dimensions. Measurement (weight or dimension): the metafield is an object with .value (the numeric amount) and .unit (the unit string like “kg” or “cm”) — you must access properties separately; direct output produces the internal object representation. Rich text (rich_text_field): stores HTML with inline formatting — use Shopify’s metafield_tag filter which wraps the rich text in a <p> tag and renders valid HTML.

The {% case type %} block in Step 5 replaces the {% if type == 'text' %} / {% elsif type == 'image' %} chain from Step 4. Case dispatch is cleaner when you have 3+ branches — it communicates “we’re choosing one of N equal options” rather than “we’re testing an ordered sequence of conditions.” The {% else %} fallback at the end is critical: if someone passes type: 'video' (a type you haven’t implemented yet), the snippet renders the value as plain text inside a metafield--fallback wrapper rather than silently producing nothing. This degrades gracefully — the metafield is visible, it’s just not in the ideal HTML format. The fallback parameter (optional string shown when the metafield itself is blank) uses the same Liquid trick as Step 2: {% if mf == blank and fallback != blank %} — both checks in one condition, short-circuit evaluation prevents evaluating fallback if mf already has a value.

Create the metafield definitions in Shopify admin. Go to Settings → Custom data → Products and click Add definition. Create one definition for each metafield your snippet will render. The fields you need for this snippet to work across all types:

• Care instructions — Type: Multi-line text, Namespace/key: custom.care_instructions. This tests the text renderer with newline_to_br.
• Size chart — Type: File (accept images only), Namespace/key: custom.size_chart. This tests the image renderer with image_url filter.
• Product weight — Type: Weight, Namespace/key: custom.product_weight. This tests the measurement renderer with .value and .unit.
• External guide — Type: URL, Namespace/key: custom.external_guide. This tests the url renderer with an <a> tag.
• Full description — Type: Rich text, Namespace/key: custom.full_description. This tests the rich_text renderer with metafield_tag filter.

All five definitions use the custom namespace — that’s the convention for admin-created metafields and it means your snippet references them as product.metafields.custom.care_instructions.

Place the snippet file and call it from your templates. Copy the Step 5 code into a new file snippets/metafield.liquid. In sections/main-product.liquid (or wherever your product template lives), add the render calls below the product description. Each metafield gets its own render tag with the appropriate type:

{% render 'metafield', metafield: product.metafields.custom.care_instructions, type: 'text', label: 'Care Instructions' %}nn{% render 'metafield', metafield: product.metafields.custom.size_chart, type: 'image', label: 'Size Chart' %}nn{% render 'metafield', metafield: product.metafields.custom.product_weight, type: 'measurement', label: 'Weight' %}nn{% render 'metafield', metafield: product.metafields.custom.external_guide, type: 'url', label: 'View Guide' %}nn{% render 'metafield', metafield: product.metafields.custom.full_description, type: 'rich_text', label: 'Full Description' %}

Each {% render %} call is independent — you can add or remove metafields without touching the snippet itself. This is the core design principle: the snippet handles how metafields render; the templates decide which metafields to show.

Naming conventions matter. Shopify metafield keys are case-sensitive and must match exactly between admin definitions and Liquid templates. Use snake_case for keys — care_instructions not CareInstructions — because Shopify admin uses snake_case by default when you create definitions. If you rename a metafield key in the admin, every {% render %} call referencing the old key silently goes blank (the null guard catches it, so no page crash — but content disappears). Document your metafield keys in a comment block at the top of metafield.liquid so the next developer (or you, six months from now) can see which keys the snippet expects.

Test with real product data. Open any product in Shopify admin, scroll to the Metafields section at the bottom, and fill in each metafield with real content. The care_instructions metafield should have multiple lines (to test newline_to_br). The size_chart metafield should have an uploaded image. The product_weight metafield should have a numeric value with a unit. After saving, preview the product on your storefront — each metafield should render in its typed wrapper with the correct HTML structure.

Add a color metafield renderer. Shopify’s color metafield type returns a hex value and an optional label. Add this {% when %} branch to the {% case type %} block in metafield.liquid:

{% when 'color' %}n  <div class="metafield metafield--color">n    {% if label != blank %}n      <span class="metafield__label">{{ label | escape }}</span>n    {% endif %}n    <spann      class="metafield__swatch"n      style="background-color: {{ mf }}"n      title="{{ mf | escape }}"n    ></span>n    <code>{{ mf | escape }}</code>n  </div>

This renders the hex value both as a colored swatch and as a readable text value. The background-color: {{ mf }} expects a valid hex string like #ff6b35 — no extra filter needed because Shopify color metafields already return hex.

Add a list metafield renderer that loops through values. The list.single_line_text_field metafield type stores multiple values. In Liquid, it stringifies as a comma-separated list by default — but to render it as proper HTML, you need to split and loop. Add this {% when %} branch:

{% when 'list' %}n  <div class="metafield metafield--list">n    {% if label != blank %}n      <h4 class="metafield__label">{{ label | escape }}</h4>n    {% endif %}n    <ul class="metafield__list">n      {% for value in mf.value %}n        <li>{{ value | escape }}</li>n      {% endfor %}n    </ul>n  </div>

The mf.value property on a list metafield returns an actual Liquid array — that’s the secret. Direct {{ mf }} on a list metafield produces a comma-concatenated string, which is never what you want for HTML. Always access .value and loop.

Use the snippet on collection pages, too. Metafields aren’t only for products — they work on collections, orders, customers, and pages. The same metafield.liquid snippet works unchanged because it accepts a generic metafield parameter, not a hardcoded product.metafields.whatever. On a collection template, you’d call:

{% render 'metafield', metafield: collection.metafields.custom.banner_text, type: 'text', label: 'Banner' %}

The snippet doesn’t care what resource the metafield belongs to — a metafield object is a metafield object. This means you can reuse the exact same file across your entire theme.

Conditional rendering — only show sections with content. A section that has three metafields shouldn’t render an empty wrapper when all three are blank. Use {% assign %} to collect the metafields into variables first, then check if any of them has a value before rendering the wrapper:

{% assign care = product.metafields.custom.care_instructions %}n{% assign size = product.metafields.custom.size_chart %}n{% assign weight = product.metafields.custom.product_weight %}nn{% if care != blank or size != blank or weight != blank %}n  <section class="product-metafields">n    {% render 'metafield', metafield: care, type: 'text', label: 'Care Instructions' %}n    {% render 'metafield', metafield: size, type: 'image', label: 'Size Chart' %}n    {% render 'metafield', metafield: weight, type: 'measurement', label: 'Weight' %}n  </section>n{% endif %}

This pattern prevents empty <section> elements from appearing in the DOM when a product has no metafield data filled in — cleaner markup, fewer layout gaps.