How to Use the ACF Repeater Field in WordPress

The Repeater field in ACF is one of the most powerful and flexible tools for developers building custom WordPress interfaces. It allows you to create structured, repeatable data blocks, ideal for things like testimonials, FAQs, image galleries, and more.

Think of the Repeater field as a table where each row can hold multiple sub-fields, and the number of rows is unlimited unless you define a limit.

In this post, we’ll explore how to use the Repeater field effectively, including how to set it up, loop through its values, and customize the output. We’ll also cover real use cases, performance tips, and alternatives.

What is the ACF Repeater Field?

The Repeater field lets you define a set of sub-fields that can be repeated again and again. It’s essentially a mini group of fields that you can duplicate as many times as needed.

• Displaying team members with name, role, photo
• FAQs with question/answer pairs
• Pricing tables
• Step-by-step instructions

How to Create a Repeater Field

You can create a repeater in any field group using the ACF UI. It’s simple and flexible:

1. Add a new field and choose Repeater as the field type
2. Define sub-fields (e.g. text, image, WYSIWYG, etc.)
3. Optionally limit the number of rows (see next section)
4. Save and assign the field group to a post type or page

Here’s some additional information which might be useful when creating a repeater field:

Setting Minimum and Maximum Rows

ACF allows you to define how many rows are required at minimum, and how many rows a user is allowed to create at most. This helps enforce layout and content rules.

• Minimum Rows: Useful when a layout should always have at least one item (e.g. one FAQ).
• Maximum Rows: Helps limit output clutter, especially in designs that expect a fixed number of items (e.g. three columns).

You can find Minimum Rows and Maximum Rows under Validation tab.

Repeater Layout Options: Table, Row, and Block

When setting up a Repeater field in ACF, you can choose how its sub-fields appear in the WordPress admin. There are three layout options:

• Table: Displays sub-fields in columns on a single row. Best for short, simple data like text or numbers.
• Row: Shows each sub-field stacked vertically. Ideal for more detailed content or longer fields.
• Block: Groups sub-fields inside a boxed container with padding . Useful for visually separating complex or styled content.

How to Display Repeater Field Data in Your Theme

To output data from a Repeater field on the frontend, you’ll use ACF’s loop functions to iterate through each row and access its sub-fields.

<?php
if ( have_rows('faq_items') ): ?>
    <div class="faq-wrapper">
        <?php while ( have_rows('faq_items') ): the_row();
            $question = get_sub_field('question');
            $answer = get_sub_field('answer');
        ?>
        <div class="faq-item">
            <h3><?php echo esc_html($question); ?></h3>
            <p><?php echo esc_html($answer); ?></p>
        </div>
        <?php endwhile; ?>
    </div>
<?php endif; ?>

Here’s a breakdown of how it works:

• have_rows('faq_items') – Checks if there are any rows in the faq_items Repeater field.
• the_row() – Moves the internal pointer to the next row so its sub-fields can be accessed.
• get_sub_field('question') and get_sub_field('answer') – Retrieve the values from each row’s sub-fields.
• esc_html() – Escapes output for safe HTML rendering, preventing XSS attacks or malformed markup.

This example will render a list of questions and answers inside a container. It’s commonly used for FAQs, but the same structure applies to team members, steps, features, or any repeatable content block.

This example will render a list of questions and answers inside a container. It’s commonly used for FAQs, but the same structure applies to team members, steps, features, or any repeatable content block.

Want to build a fully interactive FAQ section? Follow our step-by-step guide on how to create an FAQ page in WordPress using ACF Repeater and jQuery.

The “Theme Code Pro” Plugin

The Advanced Custom Fields: Theme Code Pro plugin helps you work faster by automatically generating ready-to-use PHP code for your ACF fields.

Once you create a field group, it provides the exact template code for functions like get_field(), have_rows(), and the_sub_field(), saving you time and reducing errors in your theme files.

Here’s how it looks:

Using Repeater Fields with Images

Repeater sub-fields can include any field type, including image uploads. If you want to display a user’s uploaded image, like a team member’s profile photo, you need to retrieve it properly and output it safely in your theme.

$image = get_sub_field('team_member_photo');
if( $image ):
    echo '<img src="' . esc_url($image['sizes']['medium']) . '" alt="' . esc_attr($image['alt']) . '">';
endif;

Let’s break down what this code does:

• get_sub_field('team_member_photo') retrieves the image data from the sub-field named team_member_photo.
• $image['sizes']['medium'] accesses a specific image size (in this case, the “medium” size WordPress generates automatically).
• $image['alt'] outputs the alt text added to the image in the media library.
• esc_url() and esc_attr() are used to make the output safe for HTML and prevent security issues.

Important: Set the Correct Return Format

For this code to work, the return format of the image field must be set to “Image Array” in the ACF field group settings.

You can find this option when editing your image sub-field inside the Repeater. This ensures that ACF returns a full array of image data, including sizes, URL, alt text, dimensions, and more.

If you select “Image URL” or “Image ID”, the code above will not work without modification.

Using the Image Array return format gives you the most flexibility and is recommended when you want to customize how your images appear in the template.

You can also use other sizes like thumbnail, large, or custom sizes defined with add_image_size() in your theme.

Best Practices & Performance Tips

To get the most out of the Repeater field, keep these performance and usability tips in mind:

• Always sanitize output: esc_html(), esc_url(), and esc_attr() when needed
• Minimize deep nesting inside repeaters to avoid slow admin performance
• Use PHP to register fields for better version control and full developer control
• Alternatively, enable ACF’s Local JSON feature to sync field groups with files automatically and make them part of your Git workflow
• For complex layouts or varying structures, consider using the Flexible Content field instead of nested repeaters

Advanced Example: Dynamic Team Members Grid with Tailwind

Let’s take the Repeater field further with a real-world example: a responsive, styled team members grid using Tailwind CSS. We’ll include image fallbacks, alt tag defaults, and Tailwind utility classes for layout and accessibility.

<?php
if ( have_rows('team_members') ): ?>
    <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
        <?php while ( have_rows('team_members') ): the_row();
            $name   = get_sub_field('name');
            $role   = get_sub_field('role');
            $photo  = get_sub_field('photo');
            $photo_url = $photo['sizes']['medium'] ?? get_template_directory_uri() . '/img/placeholder.jpg';
            $alt_text  = $photo['alt'] ?? $name;
        ?>
        <div class="bg-white shadow-md rounded-xl p-6 text-center flex flex-col items-center transition hover:scale-105 duration-200">
            <img src="<?php echo esc_url($photo_url); ?>" alt="<?php echo esc_attr($alt_text); ?>" class="w-24 h-24 object-cover rounded-full mb-4">
            <h3 class="text-xl font-bold"><?php echo esc_html($name); ?></h3>
            <p class="text-gray-500"><?php echo esc_html($role); ?></p>
        </div>
        <?php endwhile; ?>
    </div>
<?php endif; ?>

Here’s what this example adds:

• Fallback Image: If no image is uploaded, a default placeholder is used.
• Dynamic Alt Text: Falls back to the name if the image has no alt text.
• Tailwind Enhancements: Includes shadow, border radius, and hover effects for modern UI.
• Responsive Grid: Adjusts from 1 column on mobile to 3 columns on desktop.

This pattern is ideal for team sections, staff listings, or service cards—fully dynamic and editor-controlled through ACF.

When to Avoid Using Repeater Fields

While Repeaters are versatile, they aren’t always the best tool, especially when dealing with large or relational data.

• Use Custom Post Types for data that needs archiving or SEO
• Avoid using Repeaters for hundreds of rows, this can slow down the admin
• Avoid using Repeaters when the content needs features like categories, tags, or publishing options like drafts or scheduled posts. Use a custom post type instead.

Conclusion

The ACF Repeater field is a flexible and powerful tool for building repeatable content structures in WordPress. With careful planning, proper output handling, and limits in place, it can provide great content editing UX and help you build dynamic websites quickly.

If you’re just starting out with ACF, check out our Beginner’s Guide to Advanced Custom Fields. Want to build something more dynamic? Learn how to display repeater content in a slider with our tutorial on creating a carousel in WordPress using Slick and ACF.