Repeater

• Basic example
• Schema example
• Add button attrs
• Min/max
• Empty state
• Controls
• Custom controls
• Setting errors
• Props & Attributes
• Sections
• Accessibility
  • Keyboard Interactions

Basic example

The repeater input is for repeating groups of inputs. You can use any number of FormKit inputs within a repeater, and repeaters themselves can be infinitely nested.

By default, the repeater input has the ability to shift, add, and remove items:

Unlike most other FormKit input types, the repeater input is of type list. You can see above that the users property (our repeater's value) is an array.

Schema example

Like all other FormKit inputs, the Repeater is able to be used in a form written in FormKit schema.

Add button attrs

In the previous example, the 'Add Users' button is provided by default, and the button label is derived from the repeater's label. We're able to customize the label by using the add-button prop and setting it to a string, or remove it completely by setting it to false. Alternatively, similar to the submit-attrs prop on the FormKit's forms, we can provide an object of attributes to be applied to the button with add-attrs. In this example, we change the label of the repeater from Add Users to My custom label using the add-label prop:

Min/max

Like many other FormKit inputs, the repeater comes with a min and max prop. You can use these props to limit the number of items to be added or removed.

Empty state

When a repeater is allowed to be empty by having its min prop set to 0 and having no values, you can control the content rendered in the empty state using the empty slot.

Controls

The repeater input by default comes with a set of controls that allow you to shift, add, and remove items. You can control the visibility of these controls by setting the upControl, downControl, insertControl, and removeControl props to true or false.

Custom controls

With FormKit's repeater, you are not restricted to our default controls. You can manipulate the repeater in anyway you want:

Setting errors

You can set errors on a repeater or any repeatable item using dot notation. Here we are using the setErrors helper, but there are other methods as well:

// the 2nd argument of setErrors is input-level errors
formNode.setErrors( null, // no form errors,
  {
    // error on the repeater field:
    'teamMembers': ['There was a problem with 1 of your team members.']

    // error on a specific repeater item:
    'teamMembers.1.email': ['emily@formkit.com is already on a team.'],
  }
)

Remember, your submit handler is passed the form's core node and can be used to conveniently set errors at depth. Read more about error handling here. Here's an example of a fake backend returning errors for both the repeater and one child:

Props & Attributes

Sections

You can target a specific section of an input using that section's "key", allowing you to modify that section's classes, HTML (via :sections-schema, or content (via slots)). Read more about sections here.

Accessibility

All FormKit inputs are designed with the following accessibility considerations in mind. Help us continually improve accessibility for all by filing accessibility issues here:

Keyboard Interactions