Skip to content

Shopify metaobjects: editable content without touching theme code

From the work/ 10 min read

Shopify metaobjects for FAQs, size charts and testimonials: define the fields, fill entries in the admin and read them in a Liquid section.

  • Shopify
  • Liquid
  • Themes
In this article (9)
  1. What Shopify metaobjects are
  2. Define the fields: FAQ, size chart and testimonials
  3. Fill in entries from the admin
  4. Loop over metaobjects in Liquid
  5. Connect them to a theme section
  6. When to use metafields and when to use metaobjects
  7. Common mistakes
  8. Frequently asked questions
  9. Checklist

Shopify metaobjects store structured content, such as FAQs, size charts or testimonials, outside your theme code. You define the fields once, your team fills in entries from the admin, and the theme reads them in Liquid with metaobjects.type.values or with a metaobject_list setting on a section.

Below is the full example built around an FAQ section: the definition, the entries, the Liquid section, and when a metafield is the better choice. The code passed shopify theme check in a local scratch theme; it was not run against a live store.

What Shopify metaobjects are

The symptom is familiar: the FAQ is hard-coded inside a .liquid file, the size chart is an image pasted into every product description, and changing one answer means opening the code editor. Every copy change goes through whoever knows Liquid, and it carries the same risk of breaking the theme as a logic change.

Shopify's documentation defines a metaobject as an instance of structured data with multiple related field values. There are two parts:

  • The definition is the schema: the type (for example faq), the fields, their data types and validation rules.
  • Entries are the records that follow that definition: one per question, one per size chart, one per testimonial. Each entry has a unique handle.

Unlike a metafield, a metaobject does not belong to a product or a collection. It stands on its own and can be referenced from many places. The theme only reads it. Your team edits content in the admin, and the theme code stops changing every time a sentence does.

from definition to theme, no code edits1 · definitionfaq· question· answerSettings >Custom data2 · entriesshippingreturnspaymentsContent >Metaobjects3 · thememetaobject_listmetaobjects.faq.valuessectionfaq-metaobjectsthe admin stores the data; the theme only reads itchanging an answer no longer goes through codedefinition, entries and theme: three layersadmin paths per the Shopify Help Center

Scroll the figure sideways to see all of it

Define the fields: FAQ, size chart and testimonials

You create the definition under Content > Metaobjects or Settings > Custom data (one help page calls it Metafields and metaobjects). Per the guide to building a metaobject, you click Add definition, enter a name (the type identifier is generated and can be edited before you save), and add fields with Add field, picking a type for each. These three definitions cover the most common store content:

Definition (type)Field (key)Data type
FAQ (faq)questionsingle_line_text_field
answerrich_text_field
Size chart (size_chart)titlesingle_line_text_field
imagefile_reference (image)
notesmulti_line_text_field
Testimonial (testimonial)authorsingle_line_text_field
quoterich_text_field
productproduct_reference

Three decisions to make now rather than later:

  • The field key is what Liquid uses. question is read as faq.question.value. Rename it later and you have to edit the theme.
  • Rich text has no tables. The list of data types says rich_text_field supports headings, lists, links, bold and italics. That is why the size chart is an image plus notes, not a table typed into rich text.
  • Storefront access. Under Access, the Storefronts option is selected by default, and the help page explains how to clear it. Leave it on: a theme setting that points at the definition needs it available to the storefront.

Shopify also ships standard definitions prefixed with shopify--, such as shopify--material. If one already fits, use it before creating your own.

Fill in entries from the admin

Entries live under Content > Metaobjects: open the definition, click Add entry, fill in the fields and save. What the help page on entries makes clear:

  • Each entry gets an automatic handle, readable and unique within its type, such as shipping. You can edit it with the pencil icon, except when the definition publishes entries as web pages.
  • Changing a handle that is already in use breaks manually set references, Liquid included.
  • New entries are Active by default. A Draft entry is not published.

To attach entries to a product, create a product metafield of type metaobject in Settings, pick the faq definition and choose List of values if a product carries several questions, as the help page on referencing metaobjects describes. Then, on the product page in the admin, choose entries with Select entry. In this example that metafield is custom.faqs, of type list.metaobject_reference.

example: one FAQ as a metaobjectdefinition · faqquestionsingle_line_text_fieldanswerrich_text_fieldthe schema: keys and typesentry · shippingquestionHow long does shipping take?answer2 to 5 business days.{% for faq in metaobjects.faq.values %} {{ faq.question.value | escape }} {{ faq.answer | metafield_tag }}two fields, one entry per questionentry text: illustrative

Scroll the figure sideways to see all of it

Loop over metaobjects in Liquid

There are three ways to reach an entry from Liquid, all in the reference for the metaobject and metaobject_definition objects:

  • By handle: metaobjects.testimonial.home or metaobjects['testimonial']['home'].
  • Every entry of a type: metaobjects.faq.values, with metaobjects.faq.values_count for the total.
  • Through a reference: product.metafields.custom.faqs.value returns the entries picked on that product.

Older themes write shop.metaobjects.faq.values. Since January 28, 2025 the preferred form is metaobjects.faq.values; the old one still works for backward compatibility. Two snippets that passed theme check:

{%- assign chart = product.metafields.custom.size_chart.value -%}
{%- if chart != blank -%}
  <div class="size-chart">
    <h3>{{ chart.title.value | escape }}</h3>
    {{ chart.image | metafield_tag }}
    {{ chart.notes | metafield_tag }}
  </div>
{%- endif -%}

{%- paginate metaobjects.faq.values by 100 -%}
  {%- for faq in metaobjects.faq.values -%}
    <p>{{ faq.question.value | escape }}</p>
  {%- endfor -%}
  {{ paginate | default_pagination }}
{%- endpaginate -%}
  1. product.metafields.custom.size_chart.value reads a product metafield of type metaobject_reference. With .value you get the entry; without it, you get the metafield.
  2. != blank keeps an empty block off products that have no chart.
  3. Each field on the entry is itself a metafield: chart.title.value is the text, escaped before output.
  4. metafield_tag takes the field, not its .value. For an image it renders an <img> with loading="lazy"; for multi-line text, a <span> with line breaks.
  5. A for loop stops at 50 entries. Inside paginate, metaobjects.faq.values accepts pages of up to 250, per the paginate docs.
  6. default_pagination renders the next and previous page links.

Two more details from the system object: faq.system.handle and faq.system.type tell entries apart in a mixed list, and system.url is only set when the definition publishes entries as web pages.

Connect them to a theme section

The step that saves the most time: a section setting of type metaobject_list. With it, whoever runs the store picks which questions appear, and in what order, from the theme editor, with no code. The settings reference requires metaobject_type, accepts an optional limit whose default and maximum are both 50, and returns blank when nothing is selected. Here is the whole section, sections/faq-metaobjects.liquid:

{%- liquid
  assign faqs = section.settings.faqs
  if faqs == blank
    assign faqs = product.metafields.custom.faqs.value
  endif
  if faqs == blank
    assign faqs = metaobjects.faq.values
  endif
-%}

{%- if faqs != blank -%}
  <section class="faq">
    {%- if section.settings.heading != blank -%}
      <h2>{{ section.settings.heading | escape }}</h2>
    {%- endif -%}
    {%- for faq in faqs -%}
      <details class="faq__item">
        <summary>{{ faq.question.value | escape }}</summary>
        {{ faq.answer | metafield_tag }}
      </details>
    {%- endfor -%}
  </section>
{%- endif -%}

{% schema %}
{
  "name": "FAQ (metaobjects)",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Frequently asked questions"
    },
    {
      "type": "metaobject_list",
      "id": "faqs",
      "label": "Questions",
      "metaobject_type": "faq",
      "limit": 20
    }
  ],
  "presets": [{ "name": "FAQ (metaobjects)" }]
}
{% endschema %}

Line by line:

  1. The liquid block decides where the questions come from. First, the ones picked in the theme editor through the faqs setting.
  2. With no selection, it tries the product's custom.faqs metafield. Outside a product page, product does not exist and the value stays blank.
  3. Failing that, it takes every entry of type faq. With the publishable capability on, draft entries are left out.
  4. {%- if faqs != blank -%} renders nothing, not even the heading, when there are no questions.
  5. Each question is a <details> with its <summary>: it opens by keyboard and works with screen readers without any JavaScript.
  6. faq.question.value | escape prints the question as text; faq.answer | metafield_tag prints the rich text as a <div class="metafield-rich_text_field">.
  7. In the schema, metaobject_type: "faq" restricts the picker to that type and limit: 20 allows up to 20 entries, under the maximum of 50.
  8. presets lets you add the section from the theme editor.

Two limits on the setting: it accepts one type per setting, and if the definition does not exist on the store or is not available to the storefront, the theme editor shows an error. For Theme Store themes, Shopify allows only standard definitions in these settings, not custom ones; your store's own theme has no such restriction. For how this fits a theme that lasts, read Shopify theme architecture that survives a year.

When to use metafields and when to use metaobjects

Both use the same data types, but they solve different problems. A metafield adds a value to a resource that already exists. A metaobject creates a content type of its own that gets reused.

MetafieldMetaobject
What it isAn extra field on a product, collection, customer or orderIts own type with several fields
Where you edit itOn the resource's admin pageUnder Content > Metaobjects
ReuseOne value per resourceOne entry, many references
In Liquidproduct.metafields.custom.material.valuemetaobjects.faq.values
ExampleA T-shirt's fabricThe size chart shared by 40 T-shirts (illustrative)

The working rule: if the same content repeats across products, or has more than one field, it is a metaobject and the product points at it through a metafield. If the value only makes sense on one resource, a metafield is enough. And if the buyer types the value during checkout, it is not theme content at all; it belongs in checkout, as in add a custom field to Shopify checkout with a checkout UI extension.

metafield or metaobject: which onemetafieldmetaobjectwhat it isa field on a resourceits own type with fieldswhere it liveson a product, collection…Content > Metaobjectsreusedno: one value per resourceyes: one entry, many refsin Liquidproduct.metafields.ns.keymetaobjects.type.handleexamplea product's fabrica shared size chartif the content repeats across resources, it is a metaobjecta metafield extends, a metaobject is reusedper Shopify's custom data documentation

Scroll the figure sideways to see all of it

Common mistakes

  • Forgetting .value. faq.question is the metafield; faq.question.value is the text. The reverse holds for metafield_tag: it takes the metafield, not the value.
  • Draft entries that "don't show up". With publishable on, a Draft entry returns nil and loops skip it.
  • Renaming the handle of an entry in use. It breaks metaobjects.testimonial.home and every manually set reference.
  • Expecting more than 50 entries from a for loop. Use paginate on .values.
  • Counting a reference list with size. Reference lists use .count, for example product.metafields.custom.faqs.value.count.
  • Removing storefront access from the definition. The metaobject_list setting stops working in the editor.
  • Deleting a definition connected to the live theme. All its entries go with it, it cannot be undone, and the storefront shows errors.
  • Typing a table into rich text. The type does not support it; use an image, a list or one field per column.

Frequently asked questions

Can I show more than 50 entries of a metaobject?

Yes. A for loop stops at 50, but metaobjects.type.values works with paginate, with pages of up to 250 entries. Access by handle does not help here: it is limited to 20 unique handles per page and cannot be paginated.

Why does an entry exist in the admin but not on the storefront?

Check three things: that it is Active rather than Draft, that its handle matches the one in the code and, if it comes from a section setting, that it is selected in the theme editor. If the editor shows an error on the setting, the definition is not available to the storefront.

Does this work in a Theme Store theme?

Not with custom definitions in theme settings: the Theme Store only accepts standard definitions in metaobject and metaobject_list settings. In your store's own theme you can use your own definitions freely.

Should I write shop.metaobjects or metaobjects?

metaobjects. Shopify announced it in the changelog on January 28, 2025 as the preferred form. shop.metaobjects still works, so a theme that already uses it does not need a rewrite, but new code drops the shop. prefix.

Checklist

  • The definition has short, stable keys: question, answer.
  • Each field's type matches what you will display; no tables in rich text.
  • Storefront access stays on.
  • Entries are Active and their handles do not change once in use.
  • The product metafield is list.metaobject_reference when it holds several entries.
  • The code uses metaobjects.type, with .value to read and metafield_tag on the field.
  • The section has a metaobject_list setting with a limit of 50 or less.
  • More than 50 entries go through paginate.
  • shopify theme check passes with no errors before you push the theme.

For what comes next in how Liquid sections are put together, read Liquid gets block and partial tags in developer preview.

Saw this on Instagram? Comment METAOBJETOS on the Reel and I'll send you the guide.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 19, 2026

← Blog