HIPAA Compliant forms available September 29th, 2021. Click here to learn more.

Repeater Fields Starter Plan

A repeater field allows you to wrap a group of fields together and enable a form user to repeat the fields as many times as needed. When using a repeater fields, we strongly suggest cloaking for a better experience.

Example




Creating a Repeater Field

Create a repeater field by following these two steps:

  • Wrap the fields that will be repeated inside a <fieldset repeater>. If you add a "fieldset" tag without the repeater argument, it will be treated like a regular "fieldset" and not a repeater field.
  • Give the fieldset a "name" attribute like name="a_unique_name".
  • Wrap the inside of the <fieldset repeater> in a <div repeater-group>

Field names

Fields inside a repeater field group automatically get a __0 attached to their names. So if a field has a name of full_name, we turn it into full_name__0 for you. Any "repeated" or "cloned" fields update the __0 from the name to its new index. (__1 or __2 for example.) You can see this for yourself by inspecting the fields with your browser's devtools.

This is important to keep in mind if you want to use conditional logic or calculated fields. Instead of using fields.full_name, you would need to use fields.full_name__0.

Acceptable Fields

All field types can be used inside a repeater EXCEPT:

  • Credit-card fields.
  • Nested repeater fields.

Adding a limit

You may only want users to repeat the group of fields a certain number of times. That's easily achieved by adding a repeater-limit="" argument to your <fieldset repeater> tag.

The fields in the example below can only be repeated to a total of "3" groups.

Event hooks

For further customization, you may need to add custom logic when the Add or Remove buttons are clicked. If that's your case, you can add an id to your form and listen for the custom events we dispatch:

  • kwRepeaterAddClicked. This event is fired when the “add” button is clicked.
  • kwRepeaterAddSuccess. This event is fired when a group of fields is successfully added.
  • kwRepeaterRemoveClicked. This event is fired when the “remove” button is clicked.
  • kwRepeaterRemoveSuccess. This event is fired when a group of fields is successfully removed.

Below is a simple example of adding custom logic when the “add” button is clicked:

<form ... class="kwes-form" id="myForm">
    ...
</form>
...
<!-- Add this script after your KwesForms script --> <script> var form = document.getElementById('myForm');
form.addEventListener('kwRepeaterAddClicked', function () { alert('The add button has been clicked!'); }); </script>

Styling the Buttons

When a repeater is active, an "Add" button appears to add more fields, and a "Remove" button appears to remove fields. They both get the class of .kw-fieldgroup-button. You can use this class to add stylings to both buttons.

They also each get a separate classes in case you want to target the buttons individually.

  • The add button gets the class of .kw-fieldgroup-button-add
  • The remove button gets this class of .kw-fieldgroup-button-remove.

Notice anything wrong in our docs? Let us know.