ACF Repeater Field Basics

The ACF Repeater is an advanced field type within the Advanced Custom Fields plugin, categorized under the Layout group. This field, available in the ACF Pro version, lets you define repeatable sets of various field types.

This article focuses only on the field basics, and does not cover displaying ACF Repeater field or code snippets for Repeater fields.

Managing repeater rows in the ACF (Advanced Custom Fields) user interface is straightforward but involves a few specific actions:

1. Add a Row:
   To add a new row, click the "Add Row" button located below the repeater field table. This will create a new empty row at the bottom of the table.
2. Remove a Row:
   Hover over the last column of the row you want to remove. A minus icon ("-") will appear. Click on this icon to delete the row.
3. Clone a Row:
   Hover over the last column of the row you wish to clone, press and hold the Shift key, and click on the duplicate icon that appears. This will create an exact copy of the selected row.
4. Reorder Rows:
   Hover over the first column of the row you want to move. When the cursor changes to a dragging icon (crosshair or hand), click and drag the row up or down to the desired position.
5. Insert a Row Below a Specific Row:
   Hover over the last column of the row where you want to insert a new row below, and click the plus icon ("+") that appears. This will add a new row immediately below the selected one.

1. Subfields:
   This is where you define the fields that will be repeated within each row of the Repeater. You can add various types of fields (text, image, link, etc.) to create the structure and data you need for each repeated entry.
2. Layout:
   This setting determines how the rows within the Repeater are displayed in the admin area. Options include:
   Table: Displays rows in a tabular format, which is useful for a spreadsheet-like overview.
   Block: Displays each row as a block, offering a more visually distinct view.
   Row: Displays rows in a linear format, focusing on a simple list.
3. Pagination:
   This setting allows you to enable or disable pagination for the rows in the Repeater. Pagination helps manage large numbers of rows by splitting them across multiple pages, making the admin interface more navigable.

1. Min Rows:
   Sets the minimum number of rows that must be present in the Repeater field. This ensures that at least a certain number of entries are always provided.
2. Max Rows:
   Specifies the maximum number of rows allowed in the Repeater field. This restricts the number of entries that can be added, preventing the field from growing too large.

1. Collapsed Field:
   When enabled, editors can collapse a row, which hides all the fields except for the one specified here. This provides a cleaner preview interface, which is especially useful for setups with multiple fields.
2. Button Label:
   Customizes the label of the button used to add new rows in the Repeater field. This label can be changed to something more descriptive or fitting for the content being repeated (e.g., "Add New Testimonial").

For search-enabling purposes, the Repeater field in ACF saves each field value in a separate row within the database. For instance, if you have a Repeater field named datasheets with datasheet (text) and attachment (file) fields inside, and you have 2 rows, the database will store the following records:

datasheets_0_datasheet 
datasheets_0_attachment
datasheets_1_datasheet 
datasheets_1_attachment

As you see ACF follows the {repeater-name}_{row-index}_{field-name} format.

In the real database, it looks like this:

Performance note: While the repeater storage format may look excessive, this approach allows you to search by repeater values later. The performance worries are fair if you're expecting to have dozens of records inside each repeater instance.
Currently (Aug 2024), ACF doesn't offer table storage, as MetaBox does, so if you're using an ACF repeater with dozens of records, be ready for potential performance issues.
P.S. This does not apply if you use the Repeater field inside ACF Blocks. In this case, all the data is stored within the block's single JSON settings file.

You can use the ACF Repeater field across various locations, and it stores data consistently regardless of where it is applied:

1. Post Objects (Post, Page, Media Attachment, CPT Item, WooCommerce Product):
   All content types, including posts, pages, media attachments, and custom post types, are stored in the wp_posts table. The Repeater field data is stored in the wp_postmeta table, associated with the relevant post or custom post type item.
2. Options Page
   The Repeater field can be used on an ACF Options Page, storing its data in the wp_options table. This setup makes the Repeater data available as a global site-wide setting, useful for options like site-wide banners or settings.
3. User Profiles:
   When the Repeater field is added to user profiles, its data is stored in the wp_usermeta table, linked to the corresponding user. This can be useful for user-specific data, such as additional user information or settings.
4. Terms (e.g., Post Categories):
   The Repeater field can be attached to terms, such as post categories, tags, or custom taxonomies. In this case, the data is stored in the wp_termmeta table, connected to the specific term.
5. ACF Gutenberg Block:
   The Repeater field can be included in custom ACF Gutenberg blocks. When used within an ACF Block, the Repeater data is stored within the post_content as part of the block's JSON data structure in the wp_posts table, making it a part of the block's content.

The Repeater field is one of the cornerstone field types in ACF and can be utilized in countless ways. Here are some of the most popular real-life use cases:

1. Items Slider (e.g., Testimonials):
   Use the Repeater field to build a dynamic slider for items like testimonials. With subfields for an image, name, and testimonial text, each entry becomes a slide.
2. Teams Grid:
   Perfect for creating a team members section, the Repeater field allows you to add fields for each team member’s photo, name, job title, and bio, dynamically generating a grid layout that’s easy to update.
3. Related Items:
   Use the Repeater field to list related items such as products, blog posts, or resources. Set up subfields like a Relationship or Post Object to link with other instances.
4. FAQ Section:
   For creating a frequently asked questions (FAQ) section, the Repeater field is ideal. You can set up subfields for the question and answer.
5. Event Schedules or Timelines:
   The Repeater field is great for creating event schedules or timelines. Add subfields for the event title, date, time, description, and location. This is particularly useful for conferences, webinars, or any event with multiple sessions or activities.
6. Portfolio or Case Studies:
   When building a portfolio or case studies section, the Repeater field can help manage multiple entries. Add subfields for project name, description, date, images, and a link to the full case study. This approach makes it easy to showcase work dynamically.
7. Service Lists:
   For websites that offer multiple services, use the Repeater field to create a dynamic list of services. Include subfields for the service name, description, icon or image, and pricing, allowing easy updates to service offerings.
8. Product Features or Specifications:
   The Repeater field is excellent for displaying product features or specifications. Set up subfields for each feature, such as a title, icon, and description. This is useful for e-commerce sites where products have multiple attributes.

The Repeater field is a powerful tool, but it's crucial to understand its limitations and use it appropriately.

The most significant mistake you can make with the Repeater field is using it as a substitute for a Custom Post Type (CPT).

• Good Repeater Usage:
  A single list of testimonials on a homepage or another specific page.
• Bad Repeater Usage:
  A list of company employees used across several pages (e.g., "Our Editors," "Our Managers").

The key difference lies in how the data is used. The Repeater field is ideal for managing local, on-page data. However, if the data appears on multiple pages or needs to be queried (e.g., filtering employees by role), a CPT is the better choice.

As mentioned earlier, the Repeater field stores each row-field pair separately in the database, typically in the wp_postmeta table. If your code attempts to read all Repeater items and filter them by a specific field (like members with an editorial position) in PHP, this is an inefficient use case.

The correct approach would be to create a "Members" CPT with a role taxonomy and use a taxonomy query to filter members. In this scenario, each member's details can still be stored in ACF fields, but they are only queried when needed, optimizing performance and scalability.

Tip: If you're new to Custom Post Types and Taxonomies in WordPress, don't worry: ACF offers UI for CPT and Taxonomy management.

ACF Repeater supports an unlimited number of nested repeaters, allowing you to create a repeater within a repeater, and so on. This capability is particularly useful for complex data structures where you need multiple layers of repeating fields.

For instance, if you’re developing a custom ACF Gutenberg Block for managing awards, you might need not only a list of awards but also a nested repeater for managing multiple years of each award. This flexibility allows editors to handle intricate data setups efficiently.

Moreover, ACF Repeater does not impose restrictions on the types of fields you can nest within repeaters. You can include any field type, including Group and Gallery inside your repeater. It gives you the power to create sophisticated and dynamic content structures.

We'll show how to deal with the inner repeaters in the Code Snippets section.

ACF addons can be an important part of the workflow, and there are several addons especially useful for the ACF Repeater field:

• ACF to Custom Database Tables is an add-on for Advanced Custom Fields that saves your custom field data in a dedicated, structured database table, improving organization and performance.
• ACF Table Field Plugin extends the functionality of Advanced Custom Fields by allowing easy-to-edit tables.
• ACF Tooltip enhances the user experience by managing lengthy instruction texts in ACF fields. Instead of cluttering the edit screen, this plugin allows you to add tooltips to field labels, keeping the interface clean and space-efficient.
• WPGraphQL for ACF allows you to expose ACF fields and field groups to GraphQL, enabling seamless querying of ACF data within your GraphQL queries.

If you need to combine different field types within a single row, the Repeater field isn't the only option available in ACF. The ACF Flexible Content field is another powerful choice, offering even greater flexibility.

Unlike the static rows defined in a Repeater field, the Flexible Content field allows you to create various 'layouts' that editors can dynamically choose from. This makes it an ideal solution for more complex and customizable content structures.

For handling images or attachments specifically, consider using the ACF Gallery field instead of the Repeater. The Gallery field is designed specifically for managing collections of images or attachments, providing a more tailored solution for such needs.

When it comes to handling multiple fields, ACF takes a distinct approach. Many of its field types (such as File or Link) do not support multiple values. To manage multiple fields, you typically need to use the Repeater field to wrap these fields together.

Although some exceptions exist, like the Select field, most fields do not support multiple values without the Repeater.

Other meta plugins, such as Meta Box and Pods, provide a 'repeatable' setting for any field type. This allows you to create multiple rows for any field type without needing a separate Repeater field.

ACF’s approach with a dedicated Repeater field has its own drawbacks but also offers greater flexibility by letting you combine different field types within a single row. This can be especially useful for creating complex data structures.

While Pods doesn’t have a direct Repeater alternative, Meta Box offers the MB Group field. This feature lets you group different fields together and, along with the 'repeatable' setting, serves as a direct alternative to ACF’s Repeater. Read our comparison of the best meta field plugins to learn about the differences between vendors.