How to Use ACF Repeater Fields: Complete Guide with Examples

Krasen Slavov — Wed, 10 Jun 2026 09:00:00 +0000

ACF Repeater Fields create flexible content structures allowing unlimited field groups within a single post through row-based data entry. From basic repeater loops with have_rows() and get_sub_field() to nested repeaters and dynamic JavaScript manipulation, repeater fields eliminate rigid content limitations. This comprehensive guide teaches repeater field setup, template loops, nested structures, programmatic field registration, AJAX operations, and advanced techniques creating dynamic ACF-powered WordPress content.

What Are Repeater Fields?

Repeater Field Concept:

Repeater fields (ACF PRO feature) allow users to create sets of sub-fields that can be repeated multiple times:

Team members with name, photo, bio
Testimonials with quote, author, rating
FAQ sections with question, answer
Product features with icon, title, description
Gallery items with image, caption, link

Field Structure:

Repeater Field: "team_members"
├── Sub-field: "name" (Text)
├── Sub-field: "position" (Text)
├── Sub-field: "photo" (Image)
└── Sub-field: "bio" (Textarea)

User can add unlimited rows of these 4 fields

Creating Repeater Fields

Add Repeater via ACF UI:

Custom Fields → Field Groups
Add Field
Field Type: Repeater (ACF PRO)
Configuration:
- Field Label: Team Members
- Field Name: team_members
- Sub Fields: Add multiple sub-fields
- Button Label: “Add Team Member”
- Min/Max: Set limits (optional)
- Layout: Block, Table, or Row

Sub-Field Configuration:

Add sub-fields within repeater:

Name (Text field)
Position (Text field)
Photo (Image field)
Bio (Textarea field)

Repeater Layouts:

Block: Stack fields vertically
Table: Display in table format
Row: Horizontal layout

Basic Repeater Loop

Display Repeater Data:


if (have_rows('team_members')) :
    ?>
    class="team-section">
        Our Team
        class="team-grid">
            <?php while (have_rows('team_members')) : the_row();
                // Get sub-field values
                $name = get_sub_field('name');
                $position = get_sub_field('position');
                $photo = get_sub_field('photo');
                $bio = get_sub_field('bio');
                ?>

                class="team-member">
                    <?php if ($photo) : ?>
                        class="member-photo">
                            "$photo['sizes']['medium']); ?>"
                                 alt="$name); ?>" />
                        
                    <?php endif; ?>

                    class="member-name"><?php echo esc_html($name); ?>

                    <?php if ($position) : ?>
                        class="member-position"><?php echo esc_html($position); ?>
                    <?php endif; ?>

                    <?php if ($bio) : ?>
                        class="member-bio">
                            <?php echo wp_kses_post(wpautop($bio)); ?>
                        
                    <?php endif; ?>
                

            <?php endwhile; ?>
        
    
<?php endif; ?>

Repeater Functions

Key Functions:

// Check if repeater has rows
if (have_rows('field_name')) {
    // Rows exist
}

// Loop through rows
while (have_rows('field_name')) : the_row();
    // Access sub-fields
endwhile;

// Get sub-field value
$value = get_sub_field('sub_field_name');

// Get row count
$count = count(get_field('field_name'));

// Get row index (0-based)
$index = get_row_index();

FAQ Repeater Example

FAQ Section with Accordion:


if (have_rows('faq_items')) :
    ?>
    class="faq-section">
        Frequently Asked Questions
        class="faq-accordion">
            <?php
            $faq_index = 0;
            while (have_rows('faq_items')) : the_row();
                $question = get_sub_field('question');
                $answer = get_sub_field('answer');
                $faq_index++;
                ?>

                class="faq-item">
                    

                    "faq-$faq_index); ?>"
                         class="faq-answer"
                         hidden>
                        <?php echo wp_kses_post(wpautop($answer)); ?>
                    
                

            <?php endwhile; ?>
        
    
<?php endif; ?>

JavaScript for Accordion:

document.querySelectorAll(".faq-question").forEach(function (button) {
    button.addEventListener("click", function () {
        const expanded = this.getAttribute("aria-expanded") === "true";
        const answer = this.nextElementSibling;

        this.setAttribute("aria-expanded", !expanded);
        answer.hidden = expanded;
        this.querySelector(".faq-icon").textContent = expanded ? "+" : "−";
    });
});

Nested Repeaters

Repeater Within Repeater:


// Parent repeater: Departments
if (have_rows('departments')) :
    while (have_rows('departments')) : the_row();
        $dept_name = get_sub_field('department_name');
        ?>

        class="department">
            <?php echo esc_html($dept_name); ?>

            <?php
            // Child repeater: Employees
            if (have_rows('employees')) :
                ?>
                class="employees">
                    <?php while (have_rows('employees')) : the_row();
                        $emp_name = get_sub_field('employee_name');
                        $emp_role = get_sub_field('employee_role');
                        ?>

                        class="employee">
                            <?php echo esc_html($emp_name); ?>
                            <?php echo esc_html($emp_role); ?>
                        

                    <?php endwhile; ?>
                
            <?php endif; ?>
        

    <?php endwhile;
endif;
?>

Slider Repeater Example

Image Slider with Repeater:


if (have_rows('slider_images')) :
    ?>
    class="image-slider">
        class="slider-container">
            <?php
            $slide_index = 0;
            while (have_rows('slider_images')) : the_row();
                $image = get_sub_field('slide_image');
                $caption = get_sub_field('slide_caption');
                $link = get_sub_field('slide_link');
                $slide_index++;
                ?>

                class="slide" data-slide="$slide_index); ?>">
                    <?php if ($link) : ?>
                        "$link); ?>">
                    <?php endif; ?>

                    <?php if ($image) : ?>
                        "$image['sizes']['large']); ?>"
                             alt="$image['alt']); ?>" />
                    <?php endif; ?>

                    <?php if ($link) : ?>
                        
                    <?php endif; ?>

                    <?php if ($caption) : ?>
                        class="slide-caption">
                            <?php echo esc_html($caption); ?>
                        
                    <?php endif; ?>
                

            <?php endwhile; ?>
        

        
        
    
<?php endif; ?>

Programmatic Repeater Registration

Register Repeater via PHP:

function mytheme_register_repeater_fields() {
    if (function_exists('acf_add_local_field_group')) {
        acf_add_local_field_group(array(
            'key'    => 'group_testimonials',
            'title'  => 'Testimonials',
            'fields' => array(
                array(
                    'key'   => 'field_testimonials',
                    'label' => 'Testimonials',
                    'name'  => 'testimonials',
                    'type'  => 'repeater',
                    'layout' => 'block',
                    'button_label' => 'Add Testimonial',
                    'sub_fields' => array(
                        array(
                            'key'   => 'field_testimonial_quote',
                            'label' => 'Quote',
                            'name'  => 'quote',
                            'type'  => 'textarea',
                        ),
                        array(
                            'key'   => 'field_testimonial_author',
                            'label' => 'Author',
                            'name'  => 'author',
                            'type'  => 'text',
                        ),
                        array(
                            'key'   => 'field_testimonial_rating',
                            'label' => 'Rating',
                            'name'  => 'rating',
                            'type'  => 'number',
                            'min'   => 1,
                            'max'   => 5,
                        ),
                        array(
                            'key'   => 'field_testimonial_photo',
                            'label' => 'Photo',
                            'name'  => 'photo',
                            'type'  => 'image',
                            'return_format' => 'array',
                        ),
                    ),
                ),
            ),
            'location' => array(
                array(
                    array(
                        'param'    => 'post_type',
                        'operator' => '==',
                        'value'    => 'page',
                    ),
                ),
            ),
        ));
    }
}
add_action('acf/init', 'mytheme_register_repeater_fields');

Accessing Repeater Data Outside Loop

Get All Repeater Rows:


// Get repeater field as array
$team_members = get_field('team_members');

if ($team_members) :
    ?>
    class="team-list">
        <?php foreach ($team_members as $member) : ?>
            class="member">
                <?php echo esc_html($member['name']); ?>
                <?php echo esc_html($member['position']); ?>
            
        <?php endforeach; ?>
    
<?php endif; ?>

Conditional Display Based on Row Count

Show Different Layouts:


$features = get_field('product_features');
$feature_count = $features ? count($features) : 0;

if ($feature_count > 0) :
    // Choose layout based on count
    $grid_class = $feature_count <= 3 ? 'grid-three' : 'grid-four';
    ?>

    class="features $grid_class); ?>">
        <?php foreach ($features as $feature) : ?>
            class="feature">
                <?php if ($feature['icon']) : ?>
                    "$feature['icon']['url']); ?>"
                         alt="" class="feature-icon" />
                <?php endif; ?>

                <?php echo esc_html($feature['title']); ?>
                <?php echo esc_html($feature['description']); ?>
            
        <?php endforeach; ?>
    

<?php endif; ?>

Filtering and Sorting Repeater Data

Custom Order and Filters:


$team_members = get_field('team_members');

if ($team_members) :
    // Sort by name alphabetically
    usort($team_members, function($a, $b) {
        return strcmp($a['name'], $b['name']);
    });

    // Filter only featured members
    $featured_members = array_filter($team_members, function($member) {
        return isset($member['is_featured']) && $member['is_featured'];
    });

    foreach ($featured_members as $member) :
        ?>
        class="member featured">
            <?php echo esc_html($member['name']); ?>
        
    <?php endforeach;
endif;
?>

AJAX Add/Remove Rows

Dynamic Row Management:

// JavaScript to add row via AJAX
jQuery(document).ready(function ($) {
    $("#add-testimonial").on("click", function (e) {
        e.preventDefault();

        $.ajax({
            url: ajaxurl,
            type: "POST",
            data: {
                action: "add_repeater_row",
                post_id: $("#post_id").val(),
                field_key: "field_testimonials",
                nonce: $("#testimonial_nonce").val()
            },
            success: function (response) {
                if (response.success) {
                    location.reload();
                }
            }
        });
    });
});

PHP Handler:

function mytheme_add_repeater_row() {
    check_ajax_referer('testimonial_nonce', 'nonce');

    $post_id = absint($_POST['post_id']);
    $field_key = sanitize_text_field($_POST['field_key']);

    if (!current_user_can('edit_post', $post_id)) {
        wp_send_json_error('Insufficient permissions');
    }

    $rows = get_field($field_key, $post_id);
    $rows[] = array(
        'quote'  => '',
        'author' => '',
        'rating' => 5,
    );

    update_field($field_key, $rows, $post_id);

    wp_send_json_success();
}
add_action('wp_ajax_add_repeater_row', 'mytheme_add_repeater_row');

Best Practices

Always Check for Rows:

// Good
if (have_rows('field_name')) {
    while (have_rows('field_name')) : the_row();
        // Display content
    endwhile;
}

// Bad - no check, may cause errors
while (have_rows('field_name')) : the_row();
    // Display content
endwhile;

Escape All Output:

 echo esc_html(get_sub_field('text_field')); ?>
 echo esc_url(get_sub_field('url_field')); ?>
 echo esc_attr(get_sub_field('attribute_field')); ?>

Use Row Index for Unique IDs:

 while (have_rows('items')) : the_row(); ?>
    "item-">
        <?php the_sub_field('content'); ?>
    
<?php endwhile; ?>

Conclusion

ACF Repeater Fields provide unlimited content flexibility through row-based field groups using have_rows() loops and get_sub_field() retrieval. Create nested repeaters for complex hierarchies, register fields programmatically with acf_add_local_field_group(), manipulate repeater data as arrays for sorting and filtering, and implement AJAX operations for dynamic row management. Repeater fields eliminate rigid content structures enabling editors to add unlimited team members, testimonials, FAQ items, features, and custom content patterns maintaining consistent data structure.

External Links

Call to Action

Custom field configurations need protection. Backup Copilot Pro backs up your WordPress ACF repeater field settings and content automatically. Safeguard your flexible content structures—start your free 30-day trial today!

The post How to Use ACF Repeater Fields: Complete Guide with Examples appeared first on Developry Plugins.

nested repeaters Archives - Developry Plugins