How to Iterate Over a Metaobject List with the Mysterious "Repeater" Function

Store Design

Topic summary

A Shopify store developer is working with metaobjects to display multiple PDF documents for appliances. They’ve created a document metaobject for individual PDFs and a document_set metaobject containing a list of documents.

While building a page template, they discovered an undocumented feature called a “repeater” in Shopify’s theme editor. When connecting a metaobject list as a dynamic source to a content block, the editor automatically recognizes it as an array and displays a cyclical arrow icon. The block then outputs multiple copies—one for each item in the list—without requiring manual iteration code.

The core problem: While the repeater automatically generates blocks for each list item, there’s no apparent way to access the properties of individual metaobjects within those repeated blocks. The page template JSON contains a “repeater” key referencing the metaobject list, but documentation on how to reference the current item in the iteration is missing.

Another user shared a workaround using Liquid code to manually iterate through metaobject lists by accessing the .value property, which successfully displays individual object data. However, the original poster seeks official documentation about the repeater functionality itself, suspecting it may be a new, not-yet-perfected feature that hasn’t been fully documented by Shopify.

Summarized with AI on November 15. AI used: claude-sonnet-4-5-20250929.
1

My store sells appliances which each have multiple PDF documents we need to make available for download. To this end, I have defined two metaobjects in our store:

  1. A document metaobject represents a single PDF for download, with text and a thumbnail.
  2. A document_set contains a Metaobject list called .documents that references multiple document objects.

Currently, I am trying to set up a page template for the document_set metaobject, so that we can provide our customers with a link to a page that includes all of documents they need. Initially, my plan was to access the Metaobject list on document_set, and then iterate through it to display the text and thumbnails for all of the d****ocument metaobjects in the set.

In the process of setting this up however, I discovered a mysterious feature that I can’t find information about anywhere. When I connected the dynamic source to my custom content block, I had the option to choose documents, which is the name of the Metaobject list that contains all of the individual document metaobjects I needed to list. When I added this dynamic source, the icon for the block changed to the cyclical arrows seen in the screenshot, and the preview showed two copies of the HTML code (one copy for each document I have in the doc****ument_set.documents list).

BFWebTeam_2-1694025926589.png
BFWebTeam_2-1694025926589.png275Ă—279 3.84 KB

This is fantastic, as it implies that Shopify has identified the dynamic source as an array, and is automatically iterating through the list to output a layout block for each entry. My issue unfortunately is that I have NO IDEA how to reference the current object in the list and display its metafields.

I did some investigation to see what was providing this iterator functionality in the hope that I could find documentation. In the page source, the cyclical arrow icon is referred to as a “repeater”, and the page template JSON for this block contains a key called “repeater” with its value set to “{{ metaobject.documents.value }}” (a reference to the Metaobject list I am trying to iterate over).

BFWebTeam_3-1694026443919.png
BFWebTeam_3-1694026443919.png600Ă—401 8.42 KB

So although I can tell that this feature is called a “repeater”, I can’t find any info or documentation anywhere for how it works. It doesn’t seem to be a part of the Expanse theme I’m using, and I suspect that it is an undocumented part of Shopify itself. Does anyone have any info on this special form of block generation for list metafields? If not then I can go back to my original plan to simply write a for loop iterator, but this feature seems much more elegant and I’d like to learn how it works.

2 Likes
2

Hi @BFWebTeam , did you ever get an answer for this?

I’ve been working with trying to iterate through the Metaobjects list reference from a metafield, and just was able to print out the proper data onto a liquid section. I had tried those dynamic sources through section blocks, but found it problematic.

I am putting up specific “slides” of a client’s products on individual pages, and want that info to be dynamic per page. So I set up a page metafield name space and added a metaobject definition “slide” that has a number of entries the page metafield can select from. So the metafield “slides” was a list of metaobjects. I was able to pull those objects by iterating through the value key of that metafield array.

{% for slide in page.metafields.info.slides.value %}
<h3>{{ slide.title }} </h3>
{% endfor %}

This page here was key to helping me figure out the nuances of those objects. Previously, just printing out “page.metafields.info.slides” showed a list of graphQL references that I couldn’t even iterate through. I think the trick is seeing it as a LIST type (which may be your “repeater” suspect), and having to access the value (not values) of that list in order to access the data.

Hoping this helps?

2 Likes
3

Ah yes, I too have had to learn the nuances of Liquid arrays. They are frustratingly limited and hard to use. To clarify, I am familiar with using the value accessor method you described, and I was able to accomplish my goal through that method. I simply made this post to try and find information about this mysterious “repeater” function that I stumbled across.

I’ll use your metafield as an example of what I mean. If you add page.metafields.info.slides as a dynamic source for a content block, the editor will recognize it as an array. If that content block can have multiple items in it, then Shopify will output a content item for each slide, as if you had used {% for slide in page.metafields.info.slides %}. This behavior is the “repeater” function I’m referring to. My problem is that there’s no way for me to know what the value of slide is, and the repeater is therefore useless without being able to access the properties of individual items in the array.

I was hoping that a Shopify staff member might pop in and provide details about this undocumented behavior, but no dice. Maybe it’s a new feature that they haven’t perfected yet?

1 Like