Start here
Metaobject Lists selects metaobject entries by condition and writes the result to a metafield your theme reads. This page takes you from install to a rendered list.
Before you start
- A store with at least one metaobject definition and a few entries. If you have none, create a definition under Settings › Custom data › Metaobjects and add two or three entries.
- Access to the theme code, or to the theme editor if you only want per-product lists.
Install
Install the app from the Shopify App Store. On first open it copies your metaobject definitions and entries into its own index. A store with a few hundred entries takes a few seconds; a store with tens of thousands takes a couple of minutes. The home page shows progress and a Sync now button.
The app asks for these scopes and nothing else:
| Scope | Why |
|---|---|
write_metaobject_definitions | Read your metaobject types. Nothing is created or changed. |
write_metaobjects | Read entries and receive change webhooks. No entry is ever edited. |
write_products | Write list metafields on the shop, products and collections. |
read_content | Resolve the names of referenced pages in the preview. |
Your first list
- Choose Create list on the home page.
- Give it a name. The handle is derived from the name and becomes part of the metafield key, so keep it short.
- Under What to list, pick a type.
- Under Conditions, add a condition. The field menu lists every field on the type; the operator menu changes to suit the field.
- Under Order and size, choose a sort and, if you want, a limit.
- Watch the preview on the right update as you go.
- Choose Save. The list is written to a metafield straight away.
Read it in Liquid
Below the builder the Use in your theme section shows the Liquid for this list. Copy it into a section or snippet. For a store-wide list it looks like this:
{% assign entries = shop.metafields.lists.featured-books.value %}
{% for entry in entries %}
<h3>{{ entry.title }}</h3>
{% endfor %}
entry is a normal metaobject: every field is available by key, references resolve as usual, and entry.system.url works if the type has a page. Above the snippet, Fields to render lists every field on the type as a checkbox, with the fields of anything it references one level down. Each tick adds that field to the snippet with the right Liquid for its type, so rich text arrives with metafield_tag, images with image_url, dates with a date filter and product prices with money. Tick what the page needs: every reference field costs the storefront a lookup per entry, and a long list rendering every field of every reference can exceed Shopify's render budget.
What next
- Concepts explains the index, metafields, and how lists stay fresh.
- How-to guides walk through common lists, including relationships and per-product lists.
- Liquid reference covers paths, the 50-entry rule, and dynamic sources.