Skip to main content

metafield

A metafield attached to a parent object.

To learn about how to access a metafield on a specific object, refer to Access metafields.

Metafields support multiple data types, which determine the kind of information that's stored in the metafield. You can also output the metafield content in a type-specific format using metafield filters.


Note

You can't create metafields in Liquid. Metafields can be created in only the following ways:



Note

Metafields of type integer, json_string, and string are older implementations that don't have the properties noted on this page, and aren't compatible with metafield filters. To learn more, refer to Deprecated metafields.


Properties

Returns true if the metafield is a list type. Returns false if not.

Tip

To learn about metafield types, refer to Metafield types.

Anchor to
type
string from a set of values

The type of the metafield.

Possible values
single_line_text_field
multi_line_text_field
rich_text_field
product_reference
collection_reference
variant_reference
page_reference
file_reference
number_integer
number_decimal
date
date_time
url_reference
json
boolean
color
weight
volume
dimension
rating
money

The value of the metafield.

The following table outlines the value format for each metafield type:

TypeReturned format
single_line_text_field

multi_line_text_field
A string
rich_text_field A field that supports headings, lists, links, bold, and italics
product_reference A product object
collection_reference A collection object
variant_reference A variant object
page_reference A page object
file_reference A generic_file object

A media object (images and videos only)
number_integer

number_decimal
A number
date

date_time
A date string. To format the string, use the date filter.
url_reference A url string
json A JSON object
boolean A boolean
color A color object
weight

volume

dimension
A measurement object
rating A rating object
money A money object, displayed in the customer's local (presentment) currency.
{
"list?": false,
"type": "single_line_text_field",
"value": "Take with a meal."
}

The access path for metafields consists of two layers:

  • namespace - A grouping of metafields to prevent conflicts.
  • key - The metafield name.

Given this, you can access the metafield object with the following syntax:

{{ resource.metafields.namespace.key }}
Type: {{ product.metafields.information.directions.type }}
Value: {{ product.metafields.information.directions.value }}

Output

Type: single_line_text_field
Value: Take with a meal.
Anchor to Accessing metafields of type `json`

Accessing metafields of type json

The value property of metafields of type json returns a JSON object. You can access the properties of this object directly in Liquid, either by name or 0-based index. You can also iterate through the properties.

Temperature: {{ product.metafields.information.burn_temperature.value.temperature }}
Unit: {{ product.metafields.information.burn_temperature.value['unit'] }}

{% for property in product.metafields.information.burn_temperature.value -%}
{{ property.first | capitalize }}: {{ property.last }}
{%- endfor %}

Output

Temperature: 700
Unit: degrees

Temperature: 700
Unit: degrees
Scale: Fahrenheit
Anchor to Accessing metafields of type `list`

Accessing metafields of type list

The value property of metafields of type list returns an array. You can iterate through the array to access the values.

{% for item in product.metafields.information.combine_with.value -%}
{{ item.product.title }}
{%- endfor %}

Output

Blue Mountain Flower
Charcoal



If the list is of type single_line_text_field, then you can access the items in the array directly in Liquid using a 0-based index.

First item in list: {{ product.metafields.information.pickup_locations.value[0] }}
Last item in list: {{ product.metafields.information.pickup_locations.value.last }}

Output

First item in list: Ottawa
Last item in list: Vancouver
Anchor to Determining the length of a list metafield

Determining the length of a list metafield

The way that you determine the length of a list metafield depends on its type:

  • Reference types: Use the count property to determine the list length.
  • Non-reference types: These lists are rendered as arrays. Use the size filter to determine the number of items in the array.
# list.product_reference
Number of similar products: {{ product.metafields.information.similar_products.value.count }}

# list.single_line_text_field
Number of pickup locations: {{ product.metafields.information.pickup_locations.value.size }}

Output

# list.product_reference
Number of similar products: 2

# list.single_line_text_field
Number of pickup locations: 4
Anchor to Deprecated metafields

Deprecated metafields

Deprecated metafields are older metafield types with limited functionality. The following metafield types are deprecated:

  • integer
  • json_string
  • string

These metafield types don't have the same metafield object properties mentioned in the previous sections. Instead, they return the metafield value directly.

The following table outlines the value type for each deprecated metafield type:

Metafield typeValue type
integerAn integer
json_stringA JSON object
stringA string
Was this section helpful?