WPLake > Learning Hub > ACF Repeater Field
  • Deutsch
  • Español
  • Français
  • Italiano

ACF Repeater Field

Discover the versatility of ACF Repeater: Explore layout options, data storage, search queries, shortcode display, and nested repeater creation for flexibility.
hot air balloons are kinda like repeater fields

Key Points at a Glance

  1. Field Basics: The ACF Repeater field allows you to add repeated sets of subfields within a post or page without the need for additional Custom Post Types (CPTs), making it a versatile tool for managing content.
  2. Layout Options: ACF Repeater fields offer three layout options: Table, Block, and Row, each affecting the visual presentation of subfields for administrators and editors, providing flexibility in how content is displayed and managed.
  3. Data Storage and Retrieval: Behind the scenes, ACF Repeater fields store data in Custom Fields' Meta, organizing each repeated subfield with a unique identifier in the database, enabling efficient retrieval and manipulation through PHP.
  4. Considerations for Search Queries: developers should consider the structure of Repeater field data when designing search queries, as each subfield is stored with a specific naming convention in the database, requiring careful handling for efficient searching.
  5. Displaying Repeater Fields with Shortcodes: Advanced Views Pro plugin offers a convenient shortcode-based method for displaying ACF Repeater fields, simplifying the process of embedding complex field structures into WordPress pages without manual HTML coding.
  6. Creating Nested Repeaters: Advanced Views Pro supports nested repeaters, enabling users to create multi-level repeater structures for more complex data organization and display, offering flexibility in content management.

Table of Contents

About the Repeater field

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.

Layout options

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.

acf repeater layout settings
The three types of layout options for the ACF Repeater field. Fltr: Block Layout, Table Layout and Row Layout

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).

acf repeater pagination
Repeater pagination for a large number of rows to improve performance.

Behind the scenes in ACF

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.

Field Search Queries

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.

repeater in db
Repeater sub fields in the WP meta table.

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 
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

Display ACF Repeater with a shortcode

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 framework 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.

repeater video thumb

How-to Step-by-step

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.

Step 1. Creating a View

When you activate the Advanced Views framework 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".

Assigning fields

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”.

assigning acf fields to view
Assigning ACF fields to your ACF View with a dropdown.

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.

repeater sub field options
Assigning Sub fields to an ACF View.

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"]

Step 2. Paste the shortcode in place

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.

repeater row layout
Rows of Repeated fields for my Field Group 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.

repeater datasheets styled output
The final result of my Repeater Datasheets field group with CSS styles.

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.

Nested Repeaters

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.

Display ACF Repeater with PHP code

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) {

	// 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.

ACF Repeater type with code, video cover

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

inside a hot air balloon

Final thoughts

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.

fill repeater fields

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

Was this article helpful?

Totally useless

Slightly helpful

Very helpful

FAQ mode


Learning mode

  1. What is the Repeater field, and how does it differ from other ACF field types?

    The ACF Repeater field allows us to repeat subfields within a single field, providing a way to manage multiple sets of data without creating additional Custom Post Types (CPTs). This sets it apart from other ACF field types by offering a more structured approach to managing repeated data.

  2. What layout options for editors are available?

    You can choose between three layout options: Table, Block, and Row. Each layout option presents the subfields differently on the edit screen, catering to different preferences and usability needs.

  3. How is data stored in the database?

    Each subfield within the Repeater field is stored separately in the database, following a specific naming convention. This structure facilitates efficient data retrieval and manipulation, ensuring optimal performance.

  4. Are there performance considerations when using the Repeater field?

    While the Repeater field offers flexibility in managing multiple data entries, it may lead to slower search performance for larger datasets compared to alternatives like Custom Post Types (CPTs). You should consider the size of their dataset and the frequency of search operations when choosing the appropriate data management approach.

  5. What are the options for displaying Repeater fields?

    You can choose to display Repeater fields using either PHP code or a shortcode. While using PHP code offers more flexibility, it requires writing custom code and familiarity with the data structure. Alternatively, using a shortcode provides a more convenient and time-saving approach, especially with plugins like Advanced Views.

  6. What are Nested Repeaters, and how are they supported in the ACF ecosystem?

    Nested Repeaters are Repeater fields with subfields that also contain subfields, creating multiple levels of depth in the data structure. The Advanced Views Pro plugin, mentioned above, supports Nested Repeaters without limitations, providing you with flexibility in managing hierarchical data structures.

  7. Are there any alternatives to using the ACF Repeater field for managing repeated data entries?

    Yes, you can consider alternatives such as creating Custom Post Types (CPTs) for managing repeated data entries. While the Repeater field offers convenience, CPTs may provide better search performance for larger datasets and complex data structures.

Course navigation: ACF Plugin

Content links (21)

About the Author

Baxter Jones

With over 15 years of experience in the web industry, I specialize in design, user experience, and web best practices. I have a keen eye for detail and thrive on following a structured process in my work. I’m passionate about WordPress, considering it the best innovation since sliced bread. When I’m not at my computer, you’ll find me enjoying time in the garden.


    Leave a comment

    Reply to 

    Please be considerate when leaving a comment.

    Not shown publicly

    Got it