IntroductionAppearanceField PropertiesPermitted Sub-FieldsLabelMaximum Repeater ItemsButton TextRepeater Field NestingLimitationsEntriesExportSample FormsAll Supported FieldsNested RepeatersSample CodeExample 1Example 2Placement of the Repeater field within a form
Note: This field type, released with Gravity Forms 2.4, is currently in BETA. There is no Form Editor UI component built for this field yet. This means you cannot add this field to a form using standard Form Editor drag and drop methods. Currently this field is only intended for developers who can build their forms programmatically, or through other methods. Please open a support ticket if you are a developer who has run into trouble using this field.
Introduction
A repeater field is a collection of other Gravity Forms fields, combined together into a set that can then be used on a single form. The benefit is that when a user submits the form, the repeater field collection can be entered multiple times by the submitter, within the same single form submission.
Example: a repeater field for phone number, allowing a user to enter multiple country codes, phone numbers and associated phone number type data on a single contact form submission.Example: a repeater field consisting of attendee names and job titles, allowing a single convention registration form submission to include multiple people from the same organization.
Additionally, repeater fields can be nested within another repeater field. For example, you could allow multiple contact phone numbers to be entered for each attendee by combining the two examples mentioned above.
Save & Continue functionality is supported.
Appearance
Example of a Repeater field containing just one Name field.
Example with 3 nested Repeater fields.
Sub-fields are listed in the entry list filter so they can be searched like other fields on the form.
Field Properties
Permitted Sub-Fields
The fields property of the Repeater field is an array of fields (GF_Field objects). Supported field types are as follows:
Single Line Text; Paragraph Text; Drop Down; Multi Select; Number; Checkboxes; Radio Buttons; Name; Date; Time; Phone (「international」 format only); Address; Website; Email; List; Repeater (Nested).
Label
The value of the label property will be displayed at the top of the repeater field.
Maximum Repeater Items
The maximum number of items allowed in a repeater can be set using the maxItems field property (true/false).
Button Text
The button texts for adding and removing items for each repeater field can be defined with the field properties addButtonText and removeButtonText.
Repeater Field Nesting
A Repeater field can be nested inside another Repeater field.
There is no enforced limit to nesting depth, though form designers should consider the implications especially when designing for narrower screens.
Limitations
The following limitations exist for repeater fields as currently released. These items are likely to be addressed in future updates, so we recommend you monitor the latest releases to keep an eye on future improvements.
Conditional logic is not yet implemented.Calculations are not yet implemented.Re-ordering of items within the repeater field during form entry is not yet implemented.The rich text editor does not work within the paragraph field.The confirmation feature of the email field does not work.The 「Standard」 US format for the phone field does not work as expected.File Upload, Signature field, and Password field cannot be incorporated into a repeater fieldset.The CSS Ready classes will not work for fields inside the repeater.Dynamic population is not yet supported.Maintaining default values for the new items is not yet supported.Assigning unique tabindex attributes to new items is not yet supported. We recommend disabling the tabindex when embedding the form by using a value of 0.
Entries
All repeater field items will be displayed values that can be edited when the entry is edited.
To help with readability, the repeater field entry display uses indentation and line breaks to display the (possibly multiple) levels of input received in the single repeater field for an entry.
Export
The Conditional Logic setting for the entry export allows filtering by values of a Repeater』s sub-fields.
Note that indentations and line breaks will be present when you export the repeater data.
Sample Forms
All Supported Fields
All supported fields inside a repeater field:repeater-all-supported-fields.zip
Nested Repeaters
Three nested repeater fields:repeater-3-nested.zip
Sample Code
Example 1
How to add a Repeater field programmatically.
// Adjust your form ID
add_filter( 'gform_form_post_get_meta_149', 'add_my_field' );
function add_my_field( $form ) {
// Create a Single Line text field for the team member's name
$name = GF_Fields::create( array(
'type' => 'text',
'id' => 1002, // The Field ID must be unique on the form
'formId' => $form['id'],
'label' => 'Name',
'pageNumber' => 1, // Ensure this is correct
) );
// Create an email field for the team member's email address
$email = GF_Fields::create( array(
'type' => 'email',
'id' => 1001, // The Field ID must be unique on the form
'formId' => $form['id'],
'label' => 'Email',
'pageNumber' => 1, // Ensure this is correct
) );
// Create a repeater for the team members and add the name and email fields as the fields to display inside the repeater.
$team = GF_Fields::create( array(
'type' => 'repeater',
'description' => 'Maximum of 3 team members - set by the maxItems property',
'id' => 1000, // The Field ID must be unique on the form
'formId' => $form['id'],
'label' => 'Team Members',
'addButtonText' => 'Add team member', // Optional
'removeButtonText' => 'Remove team member', // Optional
'maxItems' => 3, // Optional
'pageNumber' => 1, // Ensure this is correct
'fields' => array( $name, $email ), // Add the fields here.
) );
$form['fields'][] = $team;
return $form;
}
// Remove the field before the form is saved. Adjust your form ID
add_filter( 'gform_form_update_meta_149', 'remove_my_field', 10, 3 );
function remove_my_field( $form_meta, $form_id, $meta_name ) {
if ( $meta_name == 'display_meta' ) {
// Remove the Repeater field: ID 1000
$form_meta['fields'] = wp_list_filter( $form_meta['fields'], array( 'id' => 1000 ), 'NOT' );
}
return $form_meta;
}
Example 2
This snippet grabs all the fields from another form, puts them into a single repeater field and adds the repeater to the form. Note that it may be necessary to set the pageNumber property.
// Adjust your form ID
add_filter( 'gform_form_post_get_meta_150', 'add_fields_from_another_form' );
function add_fields_from_another_form( $form ) {
$repeater = GF_Fields::create( array(
'type' => 'repeater',
'id' => 1000,
'formId' => $form['id'],
'label' => 'My Repeater',
'pageNumber' => 1, // Ensure this is correct
) );
$another_form = GFAPI::get_form( 103 );
foreach ( $another_form['fields'] as $field ) {
$field->id = $field->id + 1000;
$field->formId = $form['id'];
$field->pageNumber = 1; // Ensure this is correct
if ( is_array( $field->inputs ) ) {
foreach ( $field->inputs as &$input ) {
$input['id'] = (string) ( $input['id'] + 1000 );
}
}
}
$repeater->fields = $another_form['fields'];
$form['fields'][] = $repeater;
return $form;
}
// Remove the field before the form is saved. Adjust your form ID
add_filter( 'gform_form_update_meta_150', 'remove_my_field', 10, 3 );
function remove_my_field( $form_meta, $form_id, $meta_name ) {
if ( $meta_name == 'display_meta' ) {
// Remove the Repeater field: ID 1000
$form_meta['fields'] = wp_list_filter( $form_meta['fields'], array( 'id' => 1000 ), 'NOT' );
}
return $form_meta;
}
Placement of the Repeater field within a form
The placement of the repeater field in the form also needs to be controlled programmatically. Here is an example showing how you could insert the repeater field at a specific position in the fields array:
array_splice( $form['fields'], 2, 0, array( $repeater ) );
The fields array starts with an index of 0, using the above line which is adding the repeater field at index 2 would make the repeater field the third field on the form. You will need to determine what number you need to change the 2 in the example above to so that the repeater field falls between the range of fields in your form where you would like it to be located.