WordPress Repeater Field — Field Forge (ACF-Compatible)

Repeater fields are the workhorse of custom WordPress development. Team members, FAQ items, product features, testimonials, pricing tiers, social profiles — anywhere you need multiple similar records on a single post, a repeater field is the right tool. Field Forge’s repeater is fully ACF-compatible and works with the exact same have_rows() / the_sub_field() loop syntax.

What a repeater field does

A repeater field is a row template. You define which sub-fields each row contains (for example: Name, Photo, Bio), and editors can add, remove, and reorder rows at will. A single repeater field can hold from zero to hundreds of rows per post.

Example use case: team members

A field group for a “team page” contains a Team Members repeater with three sub-fields:

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

On the post edit screen, an editor clicks “Add Row,” fills in the three sub-fields, and clicks “Add Row” again for the next team member. They can drag rows to reorder, delete individual rows, and add as many rows as needed.

Supported sub-field types

Repeater sub-fields can be any of Field Forge’s 32 field types:

Basic (text, textarea, number, email, URL, etc.)
Content (image, file, WYSIWYG, oEmbed, gallery)
Choice (select, checkbox, radio, true/false, button group)
Relational (relationship, post object, page link, taxonomy, user)
jQuery (date picker, time picker, color picker)
Layout (tab, accordion, message)

The only sub-field type that doesn’t work inside a repeater is Clone (which would create infinite recursion).

Nested repeaters

Repeaters can contain other repeaters. Example: a “services” repeater where each service has a nested “features” repeater.

Services Repeater
├── Row 1: Service A
│   ├── Service Name: "Consulting"
│   ├── Description: "..."
│   └── Features Repeater
│       ├── Row 1: "Discovery workshop"
│       ├── Row 2: "Strategy doc"
│       └── Row 3: "Implementation support"
└── Row 2: Service B
    ├── Service Name: "Development"
    ├── Description: "..."
    └── Features Repeater
        ├── Row 1: "Custom code"
        └── Row 2: "QA testing"

Nesting works to any depth, though for deeply nested data you may want to consider restructuring with custom post types and relationships.

Template code (ACF-compatible)

Field Forge’s repeater uses the exact same template functions as ACF and SCF. Code written for ACF works unchanged:

<?php if (have_rows('team_members')) : ?>
  <div class="team-grid">
    <?php while (have_rows('team_members')) : the_row(); ?>
      <div class="team-member">
        <?php
          $photo = get_sub_field('photo');
          $name = get_sub_field('name');
          $bio = get_sub_field('bio');
        ?>
        <img src="<?php echo esc_url($photo['url']); ?>" alt="<?php echo esc_attr($name); ?>">
        <h3><?php echo esc_html($name); ?></h3>
        <p><?php echo esc_html($bio); ?></p>
      </div>
    <?php endwhile; ?>
  </div>
<?php endif; ?>

This code works on:

ACF (original)
Secure Custom Fields (SCF, the WordPress.org fork)
Field Forge (with the ACF compatibility layer)

If you migrate from ACF or SCF to Field Forge, this template code stays unchanged.

Nested loops

For nested repeaters, you loop inside another loop:

<?php if (have_rows('services')) : ?>
  <?php while (have_rows('services')) : the_row(); ?>
    <section>
      <h2><?php the_sub_field('service_name'); ?></h2>

      <?php if (have_rows('features')) : ?>
        <ul>
          <?php while (have_rows('features')) : the_row(); ?>
            <li><?php the_sub_field('feature_text'); ?></li>
          <?php endwhile; ?>
        </ul>
      <?php endif; ?>
    </section>
  <?php endwhile; ?>
<?php endif; ?>

The have_rows() / the_row() / get_sub_field() trio handles arbitrary nesting.

Repeater settings

When configuring a repeater in Field Forge’s visual builder:

Label — what editors see in the post editor
Name — the variable name (get_field('name'))
Minimum rows — minimum number of rows (0 for optional, 1+ for required)
Maximum rows — cap (or leave blank for unlimited)
Button label — custom text for the “Add Row” button (default: “Add Row”)
Layout — Table, Block, or Row display in the post editor
Collapsed field — which sub-field to show as the row’s collapsed label (for compact display of many rows)

Performance on large repeaters

This is where Field Forge’s custom table storage really pays off. ACF and SCF store repeater data in wp_postmeta with one row per sub-field per repeater row. A repeater with 5 sub-fields and 50 rows creates 250 meta entries per post. Loading a page with 20 such posts creates 5,000+ meta queries.

Field Forge’s custom table uses parent_id and row_index columns to store repeater data in a native relational structure. A single query fetches all repeater data for a post. Archive pages load 10–50x faster on repeater-heavy templates.

Migrating existing repeater data

When you import from ACF or SCF, Field Forge’s migration tool reconstructs nested repeater structures correctly. Parent-child relationships between rows are preserved. Nested repeaters are migrated with full hierarchy intact. After migration, your templates keep working (via the ACF compatibility layer) and queries run faster (via the custom table storage).

See the complete migration guide →

REST API output

Repeater data is exposed on the WordPress REST API and Field Forge’s custom endpoints:

{
  "team_members": [
    {
      "name": "Alice Johnson",
      "photo": {
        "id": 123,
        "url": "https://example.com/alice.jpg",
        "alt": "Alice Johnson"
      },
      "bio": "Alice is our head of engineering..."
    },
    {
      "name": "Bob Smith",
      "photo": { "id": 124, "url": "...", "alt": "Bob Smith" },
      "bio": "Bob leads the design team..."
    }
  ]
}

Perfect for headless WordPress frontends. Combined with Field Forge’s TypeScript generation, repeater data becomes fully-typed Array<SubFields> on the frontend.

Ready to use repeater fields?

Get Field Forge — from $35/year →

Repeater fields are a Pro compound type, included in every paid plan — with unlimited rows, nested repeaters, and any sub-field type.

Repeater Fields — Dynamic Row-Based Fields