Form Repeater
Overview
The Form Repeater utility allows you to create dynamic, repeatable form fields. This is particularly useful for collecting multiple entries of the same type of data, such as multiple phone numbers, addresses, or any other repeatable information.
Basic Usage
To create a form repeater, you need to set up a container with the .px-form-repeater
class and a template row that will be duplicated:
<div class="px-form-repeater" data-name="contact">
<!-- Repeater Controls -->
<div class="repeater-controls mb-15">
<button type="button" class="btn primary small fas fa-plus px-repeater-add">Add Contact</button>
</div>
<!-- Repeater Template -->
<div class="px-form-repeater-template hidden">
<div class="px-form-repeater-fields row gpx-15 mb-15">
<div class="col-12 col-md-6 mb-10">
<input type="text" placeholder="Name" class="form-control small" data-original-name="name">
</div>
<div class="col-12 col-md-6 mb-10">
<input type="tel" placeholder="Phone Number" class="form-control small" data-original-name="phone">
</div>
</div>
</div>
<!-- Repeater Container (where new rows will be added) -->
<div class="px-form-repeater-container"></div>
</div>
How It Works
The Form Repeater works as follows:
- When the user clicks the "Add" button (with class
.px-repeater-add
), a new row is created from the template - The new row is appended to the container (with class
.px-form-repeater-container
) - A "Remove" button is automatically added to each new row
- Form field names are automatically updated to use array notation (e.g.,
contact[0][name]
,contact[1][name]
, etc.)
Initialization
The Form Repeater is automatically initialized when you call the utilities function with the "form" type:
// Initialize all utilities including Form Repeater
Phenix(document).utilities();
// Or specifically initialize form utilities
Phenix(document).utilities({
type: 'form'
});
Configuration Options
Container Attributes
data-name
: The base name for the form fields (required)data-min
: Minimum number of rows (optional, default: 0)data-max
: Maximum number of rows (optional, default: unlimited)
Template Fields
Each form field in the template should have a data-original-name
attribute that will be used to generate the field names in the format: {data-name}[{index}][{data-original-name}]
<input type="text" class="form-control" data-original-name="email">
When a new row is added, this will become something like:
<input type="text" class="form-control" name="contact[0][email]">
Advanced Usage
Pre-populated Repeater
You can pre-populate the repeater with existing data by adding rows directly to the container:
<div class="px-form-repeater-container">
<!-- Pre-populated row -->
<div class="px-form-repeater-fields row gpx-15 mb-15">
<div class="col-12 col-md-6 mb-10">
<input type="text" placeholder="Name" class="form-control small" name="contact[0][name]" value="John Doe">
</div>
<div class="col-12 col-md-6 mb-10">
<input type="tel" placeholder="Phone Number" class="form-control small" name="contact[0][phone]" value="555-123-4567">
</div>
<!-- Remove button will be added automatically by the script -->
</div>
</div>
Custom Styling
The repeater rows can be styled using any Phenix utility classes. The example below uses a card-like appearance:
<div class="px-form-repeater-template hidden">
<div class="px-form-repeater-fields pdx-20 pdy-15 mb-15 bg-white border-1 border-solid border-alpha-10 radius-md">
<h4 class="mb-10">Contact Information</h4>
<div class="row gpx-15">
<div class="col-12 col-md-6 mb-10">
<input type="text" placeholder="Name" class="form-control small" data-original-name="name">
</div>
<div class="col-12 col-md-6 mb-10">
<input type="tel" placeholder="Phone Number" class="form-control small" data-original-name="phone">
</div>
</div>
</div>
</div>
Handling Form Submission
When the form is submitted, the repeater fields will be sent as an array. For example, with the configuration above, you might receive data like:
contact[0][name] = "John Doe"
contact[0][phone] = "555-123-4567"
contact[1][name] = "Jane Smith"
contact[1][phone] = "555-987-6543"
Best Practices
- Keep it Simple: Don't include too many fields in each repeater row to avoid overwhelming the user
- Provide Clear Labels: Use clear labels and placeholders to guide users
- Set Reasonable Limits: Consider using
data-max
to prevent users from adding too many rows - Validation: Apply appropriate validation to repeater fields using the Form Validation utility
- Responsive Design: Ensure your repeater layout works well on all screen sizes
Browser Compatibility
The Form Repeater utility works in all modern browsers that support JavaScript ES6 features.