Arrays

An array of objects creates a list that users can add to, remove from, duplicate, and reorder. Initialize it with an array in defaultValues. Configure object children directly on the parent or use explicit item configuration.

Usage

Use your form instance from useForm. See the initial setup.

const schema = z.object({ contacts: z.array(z.object({ phone: z.string() })) });

<ErlForm
  form={form}
  schema={schema}
  fieldConfig={{
    contacts: {
      array: { addLabel: "Add contact", maxItems: 5, reorderable: true },
      item: { phone: { label: "Phone" } },
    },
  }}
/>

Array options

Move buttons remain available without reorderable; it only controls dragging. At maxItems, Add may still look enabled, but its handler refuses to add. minItems does not automatically create initial items. Keep .min()/.max() in the schema to validate data from every source, including APIs.

New items use metadata-based empty values, not schema defaults: empty strings or the first inferred enum option, false, undefined for numbers/Date/files, empty arrays, or objects populated with empty children. Duplicating inserts the current item value without deep cloning; avoid external mutation.

Primitive arrays and matrices

Use item for primitive inputs and recursively for an array inside another array. An explicit item replaces fallback child configuration on the parent.

Use your form instance from useForm. See the initial setup.

const schema = z.object({ matrix: z.array(z.array(z.string())) });

<ErlForm
  form={form}
  schema={schema}
  fieldConfig={{
    matrix: {
      array: { addLabel: "Add row" },
      item: {
        array: { addLabel: "Add cell" },
        item: { placeholder: "Cell value" },
      },
    },
  }}
/>

item also supports tuples, unions, and records as elements. See callback scope and nested arrays.