Adding repeatable fields to a component

Components can include repeating sets of fields within the component form. A form element called a 'Field repeater' allows you to wrap one or multiple fields within a repeatable group. The Field repeater includes a button which allows the content author to add another group of fields as an array.

Important

You cannot nest a field repeater within a field repeater.
You cannot link fields outside of the Field repeater to elements within the Pattern repeater.
You cannot repeat a drop zone within a pattern repeater.

The image below shows a component form with two fields within a Field repeater that have been repeated. The 'Add button' in the bottom right of the form is used to add another set of fields. The drag handle in the top left of each group is used to sort the order using drag and drop. The 'X' button in the top right is used to remove a group from the array.

The Field repeater form element is used in conjunction with a component layout element called a Pattern repeater. The Pattern repeater allows a section of layout on the layout canvas to be repeated. When linked together, the Field repeater will repeat the layout within the Pattern repeater. The result is a component that can include a repeating set of fields that repeats a corresponding layout.

Adding repeatable fields to a component

Components can include repeating sets of fields within the component form. A form element called a 'Field repeater' allows you to wrap one or multiple fields within a repeatable group. The Field repeater includes a button which allows the content author to add another group of fields as an array.

Important

You cannot nest a field repeater within a field repeater.
You cannot link fields outside of the Field repeater to elements within the Pattern repeater.
You cannot repeat a drop zone within a pattern repeater.

The image below shows a component form with two fields within a Field repeater that have been repeated. The 'Add button' in the bottom right of the form is used to add another set of fields. The drag handle in the top left of each group is used to sort the order using drag and drop. The 'X' button in the top right is used to remove a group from the array.

The Field repeater form element is used in conjunction with a component layout element called a Pattern repeater. The Pattern repeater allows a section of layout on the layout canvas to be repeated. When linked together, the Field repeater will repeat the layout within the Pattern repeater. The result is a component that can include a repeating set of fields that repeats a corresponding layout.

The image below shows the Pattern repeater element, linked to the Field repeater component field and the resulting component form.

There are many use cases for this functionality. Some examples include:

• A gallery component where the content author can add multiple images to a single component.
• A map component where the content author can add multiple map pins to a single component.
• A slider where the content author can add multiple slides to a single component.
• A list where the content author can add multiple list items to a single component.
• A table where the content author can add multiple rows to the table.

Linking the field repeater to the pattern repeater

For the Field repeater to repeat a layout it must be linked to a Pattern repeater on the Layout canvas. To link the Field repeater to a Pattern repeater:

1. Add a Pattern repeater to the Component layout canvas
2. Add a Field repeater to the Component form builder
3. Open the settings for the Field repeater and click Apply. This will give the Field repeater a machine name of [Field.field-repeater]
4. Open the settings of the Pattern repeater on the Layout canvas
5. Enter the machine name of the Field repeater [Field.field-repeater] into the Field repeater token field and click Apply
6. The Field repeater is now linked to the Pattern repeater.

Field repeater settings

The Field repeater includes settings that allow you to control how it is used. These are:

• Minimum repeatable fields - Set the minimum number of 'repeats'. For example, you may want a slider component that includes a minimum of 3 slides.
• Maximum repeatable fields - Set the maximum number of 'repeats'. For example, you may want to limit the number images that can be added to a gallery component.
• Increment - Set the 'repeats' to be added in increments that are different to 1. For example, you may want the number of slides added to a slider component to be added in sets of two because your slider relies on an even number of slides.
• Add button title - Set the label on the button that's used to add another set of fields. 
• Sortable - Set whether the sets of fields within the repeater can be sorted using drag and drop.

The image below shows the Pattern repeater element, linked to the Field repeater component field and the resulting component form.

There are many use cases for this functionality. Some examples include:

• A gallery component where the content author can add multiple images to a single component.
• A map component where the content author can add multiple map pins to a single component.
• A slider where the content author can add multiple slides to a single component.
• A list where the content author can add multiple list items to a single component.
• A table where the content author can add multiple rows to the table.

Linking the field repeater to the pattern repeater

For the Field repeater to repeat a layout it must be linked to a Pattern repeater on the Layout canvas. To link the Field repeater to a Pattern repeater:

1. Add a Pattern repeater to the Component layout canvas
2. Add a Field repeater to the Component form builder
3. Open the settings for the Field repeater and click Apply. This will give the Field repeater a machine name of [Field.field-repeater]
4. Open the settings of the Pattern repeater on the Layout canvas
5. Enter the machine name of the Field repeater [Field.field-repeater] into the Field repeater token field and click Apply
6. The Field repeater is now linked to the Pattern repeater.

Field repeater settings

The Field repeater includes settings that allow you to control how it is used. These are:

• Minimum repeatable fields - Set the minimum number of 'repeats'. For example, you may want a slider component that includes a minimum of 3 slides.
• Maximum repeatable fields - Set the maximum number of 'repeats'. For example, you may want to limit the number images that can be added to a gallery component.
• Increment - Set the 'repeats' to be added in increments that are different to 1. For example, you may want the number of slides added to a slider component to be added in sets of two because your slider relies on an even number of slides.
• Add button title - Set the label on the button that's used to add another set of fields. 
• Sortable - Set whether the sets of fields within the repeater can be sorted using drag and drop.