<FieldArray />

function FieldArray<Item>(
  props: FieldArrayProps<Item>
): ReactNode;
type FieldArrayProps<Item> = {
  children: (
    items: FieldArrayItem<Item>[],
    helpers: FieldArrayHelpers<Item>,
    error: string | undefined
  ) => ReactNode;
  formId?: string;
  validationBehavior?: Partial<
    FieldArrayValidationBehaviorOptions
  >;
}
type FieldArrayItem<Item> = {
  defaultValue: Item,
  key: string;
}
type FieldArrayHelpers<Item> = {
  push: (item: Item) => void;
  swap: (indexA: number, indexB: number) => void;
  move: (from: number, to: number) => void;
  insert: (index: number, value: Item) => void;
  unshift: (value: Item) => void;
  remove: (index: number) => void;
  pop: () => void;
  replace: (index: number, value: Item) => void;
};

A component version of useFieldArray.

Example

FieldArrayProps

name

string

The name of the "field". If you're using array syntax, then this is the base name of the field (not include array index specifier).

Example: If you're items named todos[0], todos[1], etc, then the name would be todos.

formId

string

Optional

Allows you to use the component outside a form.

validationBehavior

{ initial: "onChange" | "onSubmit"; whenSubmitted: "onChange" | "onSubmit"; }

Optional

Allows you to configure when the field should validate. The keys (initial, whenSubmitted) are states the field/form could be in, and the values (onChange, onSubmit) are when you want to validate while in that state.

FieldItem

Each item in the array has the following properties:

defaultValue

Item

The default value for the item. When an item was created by a helper like push, this is the value that was passed to the helper.

key

string

An auto-generated key that you can use as the key prop when rendering the list of items. This key is local to this particular call to useFieldArray, so calling useFieldArray multiple times for the same field will result in different keys.

FieldArrayHelpers

Many of these helpers parallel native array helpers, but please note that, unlike the native array methods, none of these helpers return anything.

push

(item: Item) => void

Adds a new item to the end of the array.

swap

(indexA: number, indexB: number) => void

Swaps the items at the given indices.

move

(from: number, to: number) => void

Moves the item at the from index to the to index.

insert

(index: number, item: Item) => void

Inserts an item at the given index.

unshift

() => void

Removes the item at the start of the array.

pop

() => void

Removes the item at the end of the array.

remove

(index: number) => void

Removes the item at the given index.

replace

(index: number, item: Item) => void

Replaces the item at the given index.