FieldArray

    <FieldArray is a specialized <Field> that helps with list manipulations. Fields representing arrays have an additional layer of complexity, since array items may be reordered, added, or removed as well as updated. <FieldArray> helps ensure that errors and other metadata move with the data during list manipulations.

    Overview

    Provide a name mapping to an array property of the form data and <FieldArray> will inject a set of arrayHelpers for handling removing, reordering, editing and adding new items, as well as any error handling quirks that come with those operations.

    Array helpers

    FieldArray injects a set of ArrayHelpers that contain the following methods:

    interface FieldArrayHelpers<T = any> {
      /** Add an item to the beginning of the array */
      unshift(item: T): void;
      /** Add an item to the end of the array */
      push(item: T): void;
      /** Insert an item at the provided index */
      insert(item: T, index: number): void;
      /** Move an item to a new index */
      move(item: T, toIndex: number): void;
      /** Remove an item from the list */
      remove(item: T): void;
      /**
       * update or replace an item with a new one,
       * should generally be avoided in favor of using a inner Field
       * for the item to handle updates.
       *
       * Also triggers validation for the _item_
       */
      update(item: T, oldItem: T): void;
    }

    Each method is similar to a Field's onChange handler, updating and validating the array field.

    Validation

    Validation works a bit differently for FieldArrays as compared to normal Fields. Normally when a field value changes validation is triggered for that path as well as any nested paths:

    import { object, string, array } from 'yup';
    const schema = object({
      friends: array()
        .of(
          object({
            name: string().required('Required'),
          })
        )
        .min(1, 'You need at least one friend'),
    });

    A normal Field trigger validation for friends produces two errors: "Required" and "You need at least one friend". This behavior works well for object fields. Hover, it's a bit confusing if creating a new "friend" triggers validation before the user makes any changes to it.

    To address this, FieldArrays only report errors for array itself. Meaning arrayHelpers.add() will check if the min for "friends" is correct, but not if the newly added item is valid.

    Note: validation via the schema is still run for the entire friends branch, but child errors are discarded and not added to form errors. This is only relevant if each field performs some expensive validation.

    API

    import Form from 'react-formal';const FieldArray = Form.FieldArray

    <FieldArray>, unlike <Field>, does not render any component, and is essentially a render prop version of useFieldArray, accepting all the same options.

    childrenrequired

    The similar signature as providing a function to <Field> but with an additional arrayHelpers object passed to the render function:

    <Form.FieldArray>
      {(values, arrayHelpers, meta) => ... }
    </Form.FieldArray>
    type:{(value: T, arrayHelpers: FieldArrayHelpers, meta; FieldMeta) => ReactNode}

    exclusive

    Indicates whether child paths of the current FieldArray affect the active state of the FieldArray. Does not affect which paths are validated, only whether meta.valid considers child paths for its state.

    type:boolean

    mapToValue

    Map the Form value to the Field value. By default the name of the Field is used to extract the relevant property from the Form value.

    <Form.Field
      name='location'
      type="dropdownlist"
      mapToValue={formData=> pick(formData, 'location', 'locationId')}
    />
    type:MapToValue

    namerequired

    type:string

    noValidate

    Disables validation for the FieldArray.

    type:boolean

    type

    type:string