metaobject_definition

The bounded container returned from a syntactically valid metaobjects[type] lookup. Loop over values, read values_count, or resolve a storefront-visible entry directly by handle:

{% assign material = metaobjects['material']['cotton'] %}
{{ material.name }}

Entry-handle lookup is limited to 20 unique handles per definition and is memoized. values loads at most 50 entries for an ordinary loop; use paginate for pages up to 250 entries. values_count follows Shopify’s 25,001 sentinel for very large result sets. Missing or non-visible entries return nil. Publish status is enforced only for definitions with the publishable capability.

Examples

Direct entry lookup

{% assign material = metaobjects['material']['cotton'] %}
{% if material %}
  {{ material.name }} — {{ material.description.value }}
{% endif %}

Paginated definition

{% assign definition = metaobjects.testimonial %}

{% if definition.values_count > 25000 %}
  More than 25,000 testimonials
{% else %}
  {{ definition.values_count }} testimonials
{% endif %}

{% paginate definition.values by 48 %}
  {% for testimonial in definition.values %}
    <blockquote>{{ testimonial.quote.value }}</blockquote>
  {% endfor %}
  {{ paginate | default_pagination }}
{% endpaginate %}

values_count returns at most 25001; that sentinel means “more than 25,000”, not an exact count. For publishable definitions, draft entries are excluded from both values and the count. Non-publishable definitions expose their storefront-visible entries without a draft status gate.

Properties

Property	Description
`metaobject_definition.values`	Storefront-visible entries for the definition.
`metaobject_definition.values_count`	Storefront-visible entry count, capped at Shopify’s 25,001 sentinel.

Entry handles are also available as dynamic keys.

Nil and batching behavior

A syntactically valid but missing or private definition type produces an empty definition facade: values is empty, values_count is 0, and every entry-handle lookup returns nil.
An unknown handle returns nil and is memoized for the rest of the render.
More than 20 unique direct-handle lookups on one definition fail closed as nil; use values pagination for larger lists.
Reference fields used across entries are resolved in request-scoped batches.
An authored field missing from one entry returns nil for that entry.