Metafields in themes

Read a store's custom fields in sections, and declare the fields your theme needs.

Metafields are custom fields a store adds to its products, variants, collections, categories, pages, blog posts, blog categories, vendors, brands and the store itself. Fields marked visible on the storefront are available to sections.

Read metafields#

Read them under .metafields.<namespace>.<key> on any item that has them, and on shop for the store's own fields:

vascula

{% assign specs = product.metafields.specs %}
{% if specs.material %}
  <dl class="specs">
    <dt>{{ "specs.material" | t }}</dt>
    <dd>{{ specs.material }}</dd>
  </dl>
{% endif %}

<p>{{ shop.metafields.brand.tagline }}</p>

Values arrive ready to use: numbers as numbers, lists as lists, choices as their labels in the shopper's language, files as { id, url, alt_text }, and product references as product items on product pages. Check that a value is there before you print it. Every type is listed in CTX: Metafields.

vascula

{% assign pair = product.metafields.merch.pairs_with %}
{% if pair %}
  <a href="{{ pair.url }}">{{ pair.title }} · {{ pair.price.current | money }}</a>
{% endif %}

A referenced product that is not available on the storefront reads as nothing.

Declare the fields your theme needs#

If your theme relies on metafields, declare them in config/metafields.json. Installing the theme creates any that the store does not have yet, and uses the ones it already has.

json

[
  { "owner_type": "product", "namespace": "specs", "key": "material",
    "type": "string", "name": "Material", "translatable": true },
  { "owner_type": "product", "namespace": "specs", "key": "fit",
    "type": "single_select", "name": "Fit",
    "choices": [ { "key": "slim", "label": "Slim" }, { "key": "regular", "label": "Regular" } ] }
]

Field	Meaning
`owner_type`	`product`, `variant`, `collection`, `category`, `page`, `blog_post`, `blog_category`, `vendor`, `brand` or `store`.
`namespace`, `key`	The field's address: `product.metafields.<namespace>.<key>`. Up to 64 characters each.
`type`	The field type, such as `string`, `integer`, `boolean`, `single_select` or `product_reference`. See CTX: Metafields.
`name`	The name merchants see, up to 100 characters.
`description`	Optional help text.
`choices`	For `single_select` and `list.single_select`: `{ "key", "label" }` pairs.
`translatable`	For text and choice types: merchants can translate the values.

A theme can declare up to 40 fields. If the store already has a field with the same address but a different type, installation stops and names the field. Uninstalling a theme never deletes metafield values.

Use metafields elsewhere#

Connect a text setting to a metafield in the editor: see dynamic sources.
Filterable metafields appear as filters on product listings.