Rows of fields a person adds to, removes from and reorders, each row a group named by its place.
<div data-mount="links"></div>
Copy
Installation
HTML and CSS React
// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/repeater-field.css";
import { rowsFromForm } from "capsomer/behavior/repeater-field";Copy
import "capsomer/tokens.css";
import "capsomer/repeater-field.css";
import { RepeaterField } from "capsomer/react/repeater-field";Copy
Usage
<RepeaterField
legend="Footer links"
rows={links}
onChange={setLinks}
newRow={() => ({ label: "", url: "" })}
rowLabel={(i) => `Link ${i + 1}`}
addLabel="Add a link"
reorder
name="links"
>
{(row, { set, name }) => (
<TextField label="Words" name={name("label")} value={row.label} onChange={(e) => set({ label: e.target.value })} />
)}
</RepeaterField>Copy
<fieldset class="cap-field cap-repeater">
<legend class="cap-field-label">Footer links</legend>
<ol class="cap-repeater-list">
<li class="cap-repeater-row">
<fieldset class="cap-repeater-group" aria-label="Link 1">
<div class="cap-repeater-fields">...</div>
<div class="cap-repeater-actions">
<button type="button" class="cap-btn" data-size="sm" data-variant="quiet" data-cap-part="remove">Remove<span class="cap-sr-only"> Link 1</span></button>
</div>
</fieldset>
</li>
</ol>
<div class="cap-repeater-add"><button type="button" class="cap-btn" data-size="sm">Add a link</button></div>
</fieldset>Copy
Examples
At least one author, at most four: Remove is off on the last row, Add is off when full
<div data-mount="authors"></div>
Copy
With an error from the server
<div data-mount="error"></div>
Copy
API reference
RepeaterField Prop Type Required Does legendReactNodeYes The group's name, as its legend ("Links"). helpReactNodeerrorReactNoderowsT[]Yes onChange(rows: T[]) => voidYes newRow() => TYes A new, empty row. rowLabel(index: number, row: T) => stringYes The row's name ("Link 2"), from its place: its group's name, and in each button's name. children(row: T, api: RepeaterRowApi<T>) => ReactNodeYes The row's fields: labeled controls, named with api.name(key) when the form posts. addLabelstringThe add button's words. Default "Add another". minnumbermaxnumberreorderbooleanMove up and Move down on each row. namestringThe field name the rows post under. With json, script posts them as one JSON array in a hidden input of this name; rowsFromForm reads either form. jsonbooleansparenumberEmpty rows added before script runs, so a form with no script can take a new row (default 1 when name is set): the add and remove buttons need script.
Functions Function Signature Does rowsFromForm(form: FormData, name: string, keys: readonly string[]): Row[] | nullThe rows a form posted for name, with the keys asked for. With script the repeater can post them as one JSON array under name (its json prop); without, each field is posted on its own as name[i][key]. Either is read here. A row whose every value is empty is dropped (a spare row nobody filled), and values are trimmed. A JSON field that is not an array of objects is null, so the action answers with an error rather than saving an empty list over the old one. rowFieldName(name: string, index: number, key: string): stringThe posted name of one row's field: links[2][url].
Parts and data attributes Class Is .cap-repeater-actionsits own class .cap-repeater-addits own class .cap-repeater-fieldsits own class .cap-repeater-groupits own class .cap-repeater-listthe root .cap-repeater-rowits own class
State Read from [hidden]an attribute
Accessibility
Key Does Tab Through each row's fields and its buttons, then Add Enter or Space on a button Adds, removes or moves; focus lands as above
A fieldset with its legend for the whole list; a named fieldset per row. The help and the error describe the whole group.