Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 61 ยท Products, Collections and Variants

Metaobjects in Themes

Use Shopify metaobjects in a theme: definitions and entries, metaobject templates and pages, list references, FAQs, size charts, store locators and the limits.

A metafield holds one value on one resource. What if the thing you need is itself a small record: a question with an answer, a size chart row, a store address with opening hours, a team member with a photo? Putting all of that into one text field is clumsy, and merchants cannot reuse it. Metaobjects solve this. They are custom content types that a merchant defines once (an "FAQ item", a "Store"), fills with many entries, and then references from products, pages and sections.

For a theme developer, metaobjects change the question from "where do I hard-code this table?" to "which definition does my section expect, and how do I render each entry?". This lesson shows the model, the Liquid you write, how entries can become full pages, three practical patterns and the limits. It builds on Metafields in Themes, because most metaobjects are reached through a metafield reference.

Metaobjects exist only on a real store, so all theme code here is read-only and written for current Online Store 2.0 themes. The runnable examples are JavaScript stand-ins that mimic the shape of definitions and entries: they are not Shopify's implementation. Check Shopify's current reference for exact property names and limits before shipping.

Definitions and entries

Think of a database table and its rows:

  • A metaobject definition is the table. It has a type (a handle-like name such as faq_item), a display name and a list of fields. Each field has a key, a label and a type taken from the same list as metafield types (single-line text, rich text, number, file, product reference, and so on). Fields can be required or validated.
  • A metaobject entry is a row. It has values for the fields and a handle that is unique within its type. Entries have a status; only active (published) entries are visible on the storefront.
  • Capabilities are switches on the definition. The ones that matter to themes: renderable in the Online Store (entries can have their own page, with a template and SEO fields), publishable (draft or active), and translatable (each field can be translated).

Merchants create definitions and entries in the admin (Content, Metaobjects). A definition built for a theme is part of your documentation: "the size guide section needs a size_chart definition with fields label (text), chest (text) and waist (text)".

flowchart TB
  D["Definition: faq_item<br/>fields: question, answer"] --> E1["Entry: shipping-time"]
  D --> E2["Entry: returns"]
  D --> E3["Entry: warranty"]
  P["Product metafield<br/>list of faq_item"] --> E1
  P --> E3
  E2 --> PG["Own page: /pages/faq_item/returns"]

One definition, many entries; entries can be referenced from a product or have their own page.

Reading metaobjects in Liquid

There are three ways an entry reaches your template.

1. From a metafield reference

This is the common path. A product has a metafield of type metaobject_reference (one entry) or list.metaobject_reference (several). The .value is the entry or an array of entries:

LIQUID
{%- assign faqs = product.metafields.custom.faqs.value -%}
{%- if faqs != blank -%}
  <section aria-labelledby="faq-heading">
    <h2 id="faq-heading">Questions about this product</h2>
    {%- for faq in faqs -%}
      <details>
        <summary>{{ faq.question }}</summary>
        {{ faq.answer | metafield_tag }}
      </details>
    {%- endfor -%}
  </section>
{%- endif -%}

Fields are read directly by key (faq.question), and each returns the field's value or a metafield-like object depending on the type. Use metafield_tag for rich text, as in the previous lesson. An entry also has a system object with details such as faq.system.handle and faq.system.url (the last only if the entry has a page).

2. From the shop.metaobjects object

You can read all entries of a type without any product, which suits store-wide content such as a store locator:

LIQUID
{%- assign stores = shop.metaobjects.store.values -%}
{%- for store in stores -%}
  <li>{{ store.name }}, {{ store.city }}</li>
{%- endfor -%}

shop.metaobjects.<type>.values returns a limited number of entries, and a single entry can be fetched by its handle with shop.metaobjects.<type>['handle']. Because the list is capped, use it for small sets, or page through larger ones with paginate where the documentation allows. Do not rely on getting everything back for a large type.

3. Through a section setting

A section schema can contain a metaobject setting (pick one entry) or metaobject_list, with the definition type restricted by the schema. The merchant chooses entries inside the theme editor, and your Liquid reads section.settings.my_entry like any other setting. This is ideal for "pick a size chart for this block". See Schema Settings in Depth for the setting syntax.

Metaobject templates and pages

When a definition is renderable on the Online Store, each entry gets a URL (in the pattern /pages/<type>/<handle>) and the page is built from a template named after the type:

Text
templates/metaobject/store.json

Inside the template, the global metaobject object is the current entry:

LIQUID
<h1>{{ metaobject.name }}</h1>
<p>{{ metaobject.address }}</p>

A JSON template can contain sections whose settings are connected to the entry's fields through dynamic sources, so a merchant designs one page layout that is reused by every entry. Alternate templates (store.wide.json) work just like product template suffixes in JSON Templates. Remember the usual page needs: a heading, SEO fields and a canonical URL, handled by the layout as on other pages (SEO in Themes).

Three patterns

FAQs. Definition faq_item with question (single line) and answer (rich text). A product's list.metaobject_reference selects the relevant questions. Render with native <details> elements as above, and optionally output FAQ structured data from the same entries.

Size charts. Definition size_chart with a title and a list of rows. Rows can be a json field or another metaobject (size_row) referenced as a list. A product references its chart, and a modal or inline table displays it. Because many products share one chart, a merchant corrects it in one place. You build this in Project: A Size Guide with Metaobjects.

Store locator. Definition store with name, address, city, phone, opening hours (multi-line text) and an optional image. A section loops over shop.metaobjects.store.values, groups by city and offers a "Directions" link built from the address. Each store can also be its own page via the template above.

Limits and care

  • Not a database. Metaobjects are content. Do not model orders, inventory or high-volume records with them.
  • Cap on fetching. Lists read from shop.metaobjects are limited in size; plan for pagination or a different structure when you expect hundreds of entries.
  • Definition changes. Renaming or removing a field in a definition breaks templates that read it. Add fields rather than rename, and tell merchants when a field is required by your theme.
  • Missing and draft entries. A reference to a deleted or unpublished entry yields nothing. Always guard with != blank.
  • Nesting depth. An entry can reference other entries, but deep chains make templates slow and hard to reason about. Two levels is usually plenty.
  • Plan limits (number of definitions, fields, entries) can differ by plan and change over time; look them up before designing something large.

Performance rules from Liquid Performance apply: keep loops short and avoid nested loops over references.

Stand-in: rendering entries

This stand-in models a definition (with required fields) and a few entries, validates them, and renders an FAQ list with escaping. It shows how a section can enforce its own contract: entries that miss required fields are skipped with a clear message, rather than breaking the page.

JS Stand-in: validate and render FAQ entries

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The draft entry is invisible, the entry without an answer is skipped with a message, and the hostile question text arrives as plain text.

Stand-in: a store locator with grouping and a size chart lookup

A second stand-in shows two typical template tasks: grouping store entries by city and selecting a size chart row for a measurement. Both operate on plain objects shaped like entries.

JS Stand-in: group stores by city, look up a size

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In a real theme the grouping would be done with a sorted loop that compares each city with the previous one, and the chart would be a table inside a dialog. The fallback ("outside the chart") is the same idea as the guards earlier in this lesson.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the relationship between a metaobject definition and an entry?

    A definition is like a table schema with a type and fields; entries are the rows filled by merchants.
  2. 2. Which Liquid reads the question field of an entry assigned to faq?

    Fields on an entry are read directly by their key, for example faq.question.
  3. 3. What makes an entry available as its own page on the Online Store?

    The definition must be renderable on the Online Store, and the page uses the template named after its type.
  4. 4. A product references a metaobject that was later deleted. What should your Liquid do?

    A deleted or unpublished reference yields nothing, so guard before reading fields.
  5. 5. Which use is a poor fit for metaobjects?

    Metaobjects are for content. They are not a database for high-volume transactional data.

Summary

  • A metaobject definition is a schema; entries are the records merchants fill in.
  • Entries reach a theme through metafield references, shop.metaobjects, or section settings that pick them.
  • Renderable definitions give entries their own pages through templates/metaobject/<type>.json, where metaobject is the current entry.
  • Good fits: FAQs, size charts and store locators; poor fits: transactional data.
  • Guard against missing, draft and invalid entries, and respect fetch and plan limits.

Next, move from content to commerce in The Product Form and Add to Cart.