Skip to content

Repeater field

Rows of fields a person adds to, removes from and reorders, each row a group named by its place.

<div data-mount="links"></div>

Installation

// 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";

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>
<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>

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>

With an error from the server

<div data-mount="error"></div>

API reference

RepeaterField

PropTypeRequiredDoes
legendReactNodeYesThe group's name, as its legend ("Links").
helpReactNode
errorReactNode
rowsT[]Yes
onChange(rows: T[]) => voidYes
newRow() => TYesA new, empty row.
rowLabel(index: number, row: T) => stringYesThe row's name ("Link 2"), from its place: its group's name, and in each button's name.
children(row: T, api: RepeaterRowApi<T>) => ReactNodeYesThe row's fields: labeled controls, named with api.name(key) when the form posts.
addLabelstringThe add button's words. Default "Add another".
minnumber
maxnumber
reorderbooleanMove 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.
jsonboolean
sparenumberEmpty 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

FunctionSignatureDoes
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

ClassIs
.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
StateRead from
[hidden]an attribute

Accessibility

KeyDoes
TabThrough each row's fields and its buttons, then Add
Enter or Space on a buttonAdds, 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.