ACF Repeater Field Breakdown: Querying and Displaying

Advanced Custom Fields is one of the best plugins for managing meta fields and Custom Post Types (CPTs). The ACF Repeater field is one of many ACF field types and is known as a complex field, mainly due to the fact it allows you to add subfields that can be repeated over and over again when editing content. So it's true to its name.

The Repeater field is similar to the ACF Group field in that allows you to “group” sub fields, although with the Group field you can't “repeat” the sub fields, only one set of sub fields is allowed. Inside the repeater, you can use any field type, including Clone, which allows you to reuse existing fields or even a group.

A huge benefit of the Repeater field is that you don’t need to create another Custom Post Type (CPT), yet you can still display a list of items. It's often useful for the options page.

Tip: The Repeater field defines a fixed item structure, meaning all repeated items will have the same set of fields. If you need to enable the 'repeat' option for different sets of fields, consider using the Flexible field instead.

The Repeater field has Layout settings with 3 options, these are Table, Block and Row. Whichever you’ve chosen here will affect the look of the field for admins and editors.

When choosing the “Table” layout you’ll be presented with a Table of sub fields on the edit screen, with labels in the table header. When choosing the Block layout the sub fields are displayed in blocks, one after the other, and with Row, sub fields are displayed in a two column table, with labels in the first column.

Pagination in the field creation step, when switched on is useful for when you have a large number of repeater rows, this helps to improve the performance while saving (before, saving even just 10 rows took some time).

Behind the scenes, the ACF Repeater field stores the data in the Custom Fields' Meta of the current page (or post).

As you know, the repeater field allows you to have multiple rows of the same sub fields and stores it within a single main field. It sounds simple enough, but it could lead you to think that in the database, it’s also saved as a single meta field, when really it isn't.

Remember, pay close attention to the fact that, users and developers should have the option to make search queries by this field. E.g. You have several posts, each with a repeater with several rows, and you need to find them all, how would you know the specific value exists in one of the rows? This task actually appears much more often than you may think.

The Developers at Advanced Custom Fields (ACF) already thought about this, and decided to store each sub field in its own meta field, but with a special structure.

As seen above each sub field is prefixed with the row number, and the repeater name.

So, for example, you named your repeater field 'datasheets', and your sub fields are called ‘datasheet’ and ‘attachment’, then in the database they’ll be stored in the following way:

datasheets_{row-number}_datasheet and 
datasheets_{row-number}_attachment, 
where {row-number} begins from zero.

When you "request" this field from ACF with the get_field function, ACF does a trick and turns this structure into an array, so you can work in PHP in a similar fashion as with a plain array. In our example, if we need to get the sub field from the first row, we would be able to do this with the following code:

$datasheets = get_field(‘datasheets’);
echo $datasheets[0][‘datasheet’];
echo $datasheets[0][‘attachment’];

It’s important to know and understand this approach, as querying posts by repeater sub fields requires knowledge of the structure, to be able to write the correct WP_Query. You can learn how to create a WP_Query for repeater subfields in the official Docs. 

The Repeater field is a useful feature that helps you store multiple data entries, but it also has a drawback, which is the search performance for larger datasets. 

So, although querying by sub fields is possible, it eats much more server resources and takes more time when compared to Custom Post Type (CPT) items and taxonomies. 

You won’t notice the difference in case you're querying for several posts that have 5 to 10 rows each, but if we talk about a few hundred posts with lots of rows, then it’ll be much slower than the alternative CPT approach. Therefore, if you know there'll be a lot of data, and you would need to query for them, consider creating a CPT instead. Creating CPT's is possible with the ACF plugin since version 6.1 beta

Using the code way to display the fields is quite flexible, but has many disadvantages;

• It takes some time to write the code.
• You need to know the Return Types of the sub fields.
• Remembering specific key names for the response array.
• You need to manually find the correct page template in your theme and amend it.

On the other hand, there's another way that allows you to display the ACF Repeater field, (and its sub fields) without hassle. The Advanced Views plugin introduces smart templates that allow you to display ACF fields, and with the Pro version, you can display complex fields which includes the Repeater field, thus making it super easy and saving tons of time.

Advanced Views takes care of the HTML markup. We only need to choose the ACF fields to display, then copy the auto-generated shortcode and paste it into any place on a page, that’s it, there’s nothing else we need to do except style the output.

Watch a short video tutorial below on how to display ACF Repeater fields using the shortcode way.
There are more video tutorials on the Official YouTube Channel.

Skip past the video for a full texted based, step-by-step guide for displaying the ACF Repeater.

If you’d like to follow along, then please purchase, install and activate Advanced Views Pro plugin on your WordPress website. You’ll also need to install and activate Advanced Custom Fields Pro to unlock the Repeater field type.

Now that you’re ready, let’s continue.

When you activate the Advanced Views plugin a new item appears in the admin menu, called "Advanced Views". The item has several sub-items, but in our case, we'll be working only with the one called "Views".

Click that menu item to open the Views page and then click the 'Add New' button to create a View.

On the new page give your View a name, it can be anything that describes the View. I've called my View "download datasheets".

It’s time to assign the Repeater field and subfields to your View. Click on the ‘Add Field’ button and select your ‘Group’ from the dropdown. In my case, I've called the group “Download Datasheets”.

Then continue to select the target field from the list. I've selected “Datasheet”.

You'll notice that each field will have it's field type shown in brackets. In this case you should see the type as “repeater”. Continue by switching to the “Sub fields” tab and then add your sub fields from the list, one at a time and then insert a label for each field as required.

Pro Tip: Add the first field, then duplicate the row and change the field to another. This saves time not having to first select the Field Group each time and then choosing the field.

Click the “Publish” button to save and publish your View. Shortcodes are then generated and shown on the right of the View edit screen. Read more about the different shortcodes and their uses in the Advanced Views docs.

Copy the first shortcode without the object-id parameter to the clipboard.
E.g. [acf_views view-id="123" name="Name of View"]

Everything should now be ready to display your ACF Repeater field. Go to your target page (the page where you’ve located your ACF fields) and on the edit screen, paste the copied shortcode anywhere you’d like in the page content.

In case you're using the Gutenberg editor: click on the plus button in the top bar and choose the "Shortcode" block from the list, then paste your shortcode in the block.

Now, all that’s left to do is to fill in the fields (sub fields really). Add more rows of sub fields as you need them. 

In my case I have a ‘Datasheet’ text field, and a file field I’ve called ‘Attachment’. I ended up using three Repeater rows for English, French and German datasheets.

Be sure to save your page by clicking “Update” or “Publish”, then visit your page. As a result and if you’ve done it all correctly then you should see the list of Repeater items.

If you don’t see your list of items, then go back and edit the page. For instance, make sure you’ve filled the fields and saved the page, if they are indeed filled, then go further back to your View edit, were you assigned the fields. Then double check they're assigned from the correct field group. Consequently if you've left the fields unfilled on the page or post then there will be nothing to display.

There are times that you'll need to have what is known as a Nested Repeater, which is a Repeater field with a Repeater Sub field, which also has sub fields. Therefore three levels of depth, apposed to the usual one or two levels.

Advanced Views Pro supports nested repeaters without any limitations. See step by step guide in the docs.

Learn how to display repeater fields on WooCommerce product pages, so relevant information is seen by potential customers.

Displaying Repeater sub fields means you’ll need to create HTML markup, for the fields and for the variables for when fields are filled.

Here's some examples of PHP code needed to display sub fields and a basic image slider.

PHP code to display Repeater sub field values with the Basic loop.

$items = get_field('repeater');
// value can be null, convert in case the array is empty
$items = $items ?: [];

echo "<div class='view'>";
foreach ($items as $item) {
	printf("<div class='view__address'>%s</div>", $item['address']);
}
echo "</div>";

PHP code to display a basic image slider.

$items = get_field('repeater');
// value can be null, convert in case the array is empty
$items = $items ?: [];

echo "<ul class='slides'>";
foreach ($items as $item) {
	// Return Format of the image must be 'ID'
	$imageId = $item['image'];

	// skip if the image is not selected
	if (!$imageId) {
    	continue;
	}

	// wp_get_attachment_image() will create HTML markup for the selected image (the img tag)
	printf("<div class='slides__slide'>%s</div>", wp_get_attachment_image($imageId, 'full'));
}
echo "</ul>";

To get additional information, watch the video below and read the official ACF article.

If you're interested in the more technical side of WordPress, consider reading about what good WordPress developers must know.

In this tutorial we’ve shown you how to use and display ACF Repeater fields in two ways, first with coding and the more practical and easier way with using a shortcode.

A View can contain any number of fields of different types, which means you could extend your View at any time, Advanced Views supports all available field types with extended support for complex fields.

Get more info about the plugin we used in our shortcode example, by visiting the official plugin page.

Only the sky’s the limit now with what you can achieve with WordPress, Advanced Custom Fields and Advanced Views. Good Luck.