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

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

Tip
To learn about metafield types, refer to Metafield types.
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
value: The value of the metafield.

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

Type Returned 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.

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

Type	Returned 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."

}

{
  "list?": false,
  "type": "single_line_text_field",
  "value": "Take with a meal."
}

Access metafields

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:

Type: {{ product.metafields.information.directions.type }}

Value: {{ product.metafields.information.directions.value }}

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

{
  "product": {
    "metafields": {}
  }
}

Output

Type: single_line_text_field

Value: Take with a meal.

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 %}

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 %}

{
  "product": {
    "metafields": {}
  }
}

Output

Temperature: 700

Unit: degrees

Temperature: 700

Unit: degrees

Scale: Fahrenheit

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 -%}

{%- endfor %}

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

{
  "product": {
    "metafields": {}
  }
}

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 }}

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

{
  "product": {
    "metafields": {}
  }
}

Output

First item in list: Ottawa

Last item in list: Vancouver

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 }}

# 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 }}

{
  "product": {
    "metafields": {}
  }
}

Output

# list.product_reference

Number of similar products: 2

# list.single_line_text_field

Number of pickup locations: 4

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 type	Value type
`integer`	An integer
`json_string`	A JSON object
`string`	A string

Was this section helpful?

metafield

Properties

Access metafields

Output

Accessing metafields of type json

Output

Accessing metafields of type list

Output

Output

Determining the length of a list metafield

Output

Deprecated metafields

Accessing metafields of type `json`

Accessing metafields of type `list`