Overview #

The PZ Repeater block allows you to create dynamic forms where users can duplicate form fields on the frontend by clicking a “+” button. Each duplicated set of fields gets unique field names with numeric suffixes, and the data is organized into arrays for easy processing. While the pzrepeater block is straightforward compared to standard programming methods for achieving the same results, it’s a little more complex than typical fields. Generally, you’ll have to write at least a small amount of PHP code in a submit file to get the overall results you’re looking for.

A typical sort of use for the repeater block is when a user is likely to provide more than one entry for something you’re asking about. If you ask a user for information about their children, for instance, they’ll need to enter different information for each of their kids. So you’ll set up a repeater block with the fields required to handle one child and, on the front end, they’ll duplicate the block and its fields for each additional kid.

How to Use #

1. Adding the Repeater Block #

1. In the WordPress block editor, search for “PZ Repeater” or find it in the PeakZebra category
2. Add the block to your form
3. Inside the repeater block, add any form fields you want to be repeatable (text fields, number fields, dropdowns, etc.)

2. Configuring the Repeater Block #

In the block settings panel (right sidebar), you can configure:

• Repeater ID: A unique identifier for this repeater block (optional but recommended)
• Button Text: Text to display on the add button (default: “+”)
• Button CSS Class: Custom CSS class for the add button
• Container CSS Class: Custom CSS class for the repeater container
• Item CSS Class: Custom CSS class for each repeater item

3. Frontend Behavior #

• Users see the initial set of form fields
• A “+” button appears below the fields
• Clicking the “+” button duplicates all fields in the repeater
• The “+” button moves to the newest duplicate
• Previous “+” buttons are hidden
• Each duplicate has field names with numeric suffixes (e.g., fieldname_0, fieldname_1)

Field Naming Convention #

The repeater block automatically handles field naming:

• First item: Fields have _0 suffix (e.g., name_0, email_0)
• Second item: Fields have _1 suffix (e.g., name_1, email_1)
• Third item: Fields have _2 suffix (e.g., name_2, email_2)
• And so on…

Processing Repeater Data #

In Form-Specific Submit Files #

When a form with repeater blocks is submitted, the data is automatically organized into the $repeater_data array. This array is available in your form-specific submit files (e.g., submit/my-form.php).

// Access the repeater data
foreach ($repeater_data as $index => $item_fields) {
    echo "Repeater item $index:\n";
    foreach ($item_fields as $field_name => $field_value) {
        echo "  $field_name: $field_value\n";
    }
}

Example Output #

If you have a repeater with fields name and email, and the user creates 2 duplicates, the data structure would be:

$repeater_data = [
    0 => [
        'name' => 'John Doe',
        'email' => 'john@example.com'
    ],
    1 => [
        'name' => 'Jane Smith', 
        'email' => 'jane@example.com'
    ],
    2 => [
        'name' => 'Bob Johnson',
        'email' => 'bob@example.com'
    ]
];

Processing Multiple Repeaters #

If you have multiple repeater blocks on the same form, all their data will be combined into the same $repeater_data array. You can distinguish between different repeaters by checking field names or using unique field prefixes.

Generally, you’ll only need one repeater block per form and it’s a lot easier to keep things straight if you stick to one form and one repeater block per page.

Best Practices #

1. Use unique Repeater IDs when you have multiple repeater blocks on the same form
2. Keep field names simple – the repeater will add numeric suffixes automatically
3. Test thoroughly – ensure your form processing handles the array structure correctly

Limitations #

• The repeater block only works with form fields (not content blocks)
• Field names are automatically suffixed – don’t manually add numbers to field names
• All fields in a repeater item are duplicated together
• The maximum number of duplicates is limited only by browser performance

Troubleshooting #

Missing Fields in First Item #

If fields in the first repeater item are missing or empty, ensure you’ve run the build process after any recent changes:

cd pzforms && npm run build

Field Names Not Updating #

If field names aren’t getting numeric suffixes, check that the repeater block’s view script is loading properly on the frontend.

Data Not Appearing in Submit Script #

Ensure your form-specific submit file is accessing the $repeater_data variable correctly and that the field names match what you expect.