useFieldArray

This hook supplies you with functions for manipulating the array/list of fields, it's fast! See the Arrays and Lists to learn more.

const [fields, helpers] = useFieldArray(name, config);

Name

string

The name of the field. We must provide it when using this hook.

Config

An object with the following options:

formId

string

The corresponding ID of the useForm hook. We only need it when using multiple form hooks at the same time.

defaultValue

string

The default value of the field. Useful for dealing with the case of conditional fields.

validation

(value: any, values: FormValues) => any | Promise<any>

A synchronous/asynchronous function that is used for the field-level validation.

Fields

string[]

An array that holds field names (e.g. foo[0], foo[1]), which can be used for the key and name attributes of a field.

• It refers to the location of the field in the form state. If the referenced value isn't an array type, returns an empty array instead.
• It doesn't include the field data. If you need to access the data, use the use or getState methods.

const [fields] = useFieldArray("foo", { defaultValue: [{ name: "Iron Man" }] });
// The first parameter of the callback supplies you a field name (e.g. foo[0], foo[1])fields.map((fieldName) => (  <input    key={fieldName} // Use the "fieldName" as the key    name={`${fieldName}.name`} // Use the "fieldName" + "YOUR PATH" as the name  />));

Helpers

An object with the following methods:

push

(value: FieldValue, options?: Object) => void

Add a value to the end of an array.

const handleAdd = () => {  push(    { name: "Iron Man" },    {      shouldTouched: false, // (Default = false) Set the field as touched      shouldDirty: true, // (Default = true) Set the field as dirty    }  );};

insert

(index: number, value: FieldValue, options?: Object) => void

Insert an element at a given index into the array.

const handleInsert = () => {  insert(    0,    { name: "Iron Man" },    {      shouldTouched: false, // (Default = false) Set the field as touched      shouldDirty: true, // (Default = true) Set the field as dirty    }  );};

swap

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

Swap two values in an array.

move

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

Move an element in an array to another index.

remove

(index: number) => FieldValue

Remove an element at an index of an array and return it.

Example

The example demonstrates the basic usage of this hook.

import { useForm, useFieldArray } from "react-cool-form";
const App = () => {  const { form } = useForm({    defaultValues: { foo: [{ name: "Iron Man" }] },  });  const [fields, { push, insert, move, swap, remove }] = useFieldArray("foo");
  return (    <form ref={form}>      {/* The first parameter of the callback supplies you a field name (e.g. foo[0], foo[1]) */}      {fields.map((fieldName) => (        <input          key={fieldName} // Use the "fieldName" as the key          name={`${fieldName}.name`} // Use the "fieldName" + "YOUR PATH" as the name        />      ))}    </form>  );};