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)
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.
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) | question | single_line_text_field |
answer | rich_text_field | |
Size chart (size_chart) | title | single_line_text_field |
image | file_reference (image) | |
notes | multi_line_text_field | |
Testimonial (testimonial) | author | single_line_text_field |
quote | rich_text_field | |
product | product_reference |
Three decisions to make now rather than later:
- The field key is what Liquid uses.
questionis read asfaq.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_fieldsupports 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.
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.homeormetaobjects['testimonial']['home']. - Every entry of a type:
metaobjects.faq.values, withmetaobjects.faq.values_countfor the total. - Through a reference:
product.metafields.custom.faqs.valuereturns 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 -%}
product.metafields.custom.size_chart.valuereads a product metafield of typemetaobject_reference. With.valueyou get the entry; without it, you get the metafield.!= blankkeeps an empty block off products that have no chart.- Each field on the entry is itself a metafield:
chart.title.valueis the text, escaped before output. metafield_tagtakes the field, not its.value. For an image it renders an<img>withloading="lazy"; for multi-line text, a<span>with line breaks.- A
forloop stops at 50 entries. Insidepaginate,metaobjects.faq.valuesaccepts pages of up to 250, per the paginate docs. default_paginationrenders 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:
- The
liquidblock decides where the questions come from. First, the ones picked in the theme editor through thefaqssetting. - With no selection, it tries the product's
custom.faqsmetafield. Outside a product page,productdoes not exist and the value staysblank. - Failing that, it takes every entry of type
faq. With the publishable capability on, draft entries are left out. {%- if faqs != blank -%}renders nothing, not even the heading, when there are no questions.- Each question is a
<details>with its<summary>: it opens by keyboard and works with screen readers without any JavaScript. faq.question.value | escapeprints the question as text;faq.answer | metafield_tagprints the rich text as a<div class="metafield-rich_text_field">.- In the schema,
metaobject_type: "faq"restricts the picker to that type andlimit: 20allows up to 20 entries, under the maximum of 50. presetslets 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.
| Metafield | Metaobject | |
|---|---|---|
| What it is | An extra field on a product, collection, customer or order | Its own type with several fields |
| Where you edit it | On the resource's admin page | Under Content > Metaobjects |
| Reuse | One value per resource | One entry, many references |
| In Liquid | product.metafields.custom.material.value | metaobjects.faq.values |
| Example | A T-shirt's fabric | The 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.
Scroll the figure sideways to see all of it
Common mistakes
- Forgetting
.value.faq.questionis the metafield;faq.question.valueis the text. The reverse holds formetafield_tag: it takes the metafield, not the value. - Draft entries that "don't show up". With publishable on, a Draft entry returns
niland loops skip it. - Renaming the handle of an entry in use. It breaks
metaobjects.testimonial.homeand every manually set reference. - Expecting more than 50 entries from a
forloop. Usepaginateon.values. - Counting a reference list with
size. Reference lists use.count, for exampleproduct.metafields.custom.faqs.value.count. - Removing storefront access from the definition. The
metaobject_listsetting 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_referencewhen it holds several entries. - The code uses
metaobjects.type, with.valueto read andmetafield_tagon the field. - The section has a
metaobject_listsetting with alimitof 50 or less. - More than 50 entries go through
paginate. shopify theme checkpasses 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

Published November 19, 2026