<FieldArray />

<FieldArray /> is a component that helps with common array/list manipulations. You pass it a name property with the path to the key within values that holds the relevant array. <FieldArray /> will then give you access to array helper methods via render props. For convenience, calling these methods will trigger validation and also manage touched for you.

1 import React from 'react';
2 import { Formik, Form, Field, FieldArray } from 'formik';
3 
4 // Here is an example of a form with an editable list.
5 // Next to each input are buttons for insert and remove.
6 // If the list is empty, there is a button to add an item.
7 export const FriendList = () => (
8   <div>
9     <h1>Friend List</h1>
10     <Formik
11       initialValues={{ friends: ['jared', 'ian', 'brent'] }}
12       onSubmit={values =>
13         setTimeout(() => {
14           alert(JSON.stringify(values, null, 2));
15         }, 500)
16       }
17       render={({ values }) => (
18         <Form>
19           <FieldArray
20             name="friends"
21             render={arrayHelpers => (
22               <div>
23                 {values.friends && values.friends.length > 0 ? (
24                   values.friends.map((friend, index) => (
25                     <div key={index}>
26                       <Field name={`friends.${index}`} />
27                       <button
28                         type="button"
29                         onClick={() => arrayHelpers.remove(index)} // remove a friend from the list
30                       >
31                         -
32                       </button>
33                       <button
34                         type="button"
35                         onClick={() => arrayHelpers.insert(index, '')} // insert an empty string at a position
36                       >
37                         +
38                       </button>
39                     </div>
40                   ))
41                 ) : (
42                   <button type="button" onClick={() => arrayHelpers.push('')}>
43                     {/* show this when user has removed all friends from the list */}
44                     Add a friend
45                   </button>
46                 )}
47                 <div>
48                   <button type="submit">Submit</button>
49                 </div>
50               </div>
51             )}
52           />
53         </Form>
54       )}
55     />
56   </div>
57 );

`name: string`

The name or path to the relevant key in values.

`validateOnChange?: boolean`

Default is true. Determines if form validation should or should not be run after any array manipulations.

FieldArray Array of Objects

You can also iterate through an array of objects, by following a convention of object[index].property or object.index.property for the name attributes of <Field /> or <input /> elements in <FieldArray />.

1 <Form>
2   <FieldArray
3     name="friends"
4     render={arrayHelpers => (
5       <div>
6         {values.friends.map((friend, index) => (
7           <div key={index}>
8             {/** both these conventions do the same */}
9             <Field name={`friends[${index}].name`} />
10             <Field name={`friends.${index}.age`} />
11 
12             <button type="button" onClick={() => arrayHelpers.remove(index)}>
13               -
14             </button>
15           </div>
16         ))}
17         <button
18           type="button"
19           onClick={() => arrayHelpers.push({ name: '', age: '' })}
20         >
21           +
22         </button>
23       </div>
24     )}
25   />
26 </Form>

FieldArray Validation Gotchas

Validation can be tricky with <FieldArray>.

If you use validationSchema and your form has array validation requirements (like a min length) as well as nested array field requirements, displaying errors can be tricky. Formik/Yup will show validation errors inside out. For example,

1 const schema = Yup.object().shape({
2   friends: Yup.array()
3     .of(
4       Yup.object().shape({
5         name: Yup.string().min(4, 'too short').required('Required'), // these constraints take precedence
6         salary: Yup.string().min(3, 'cmon').required('Required'), // these constraints take precedence
7       })
8     )
9     .required('Must have friends') // these constraints are shown if and only if inner constraints are satisfied
10     .min(3, 'Minimum of 3 friends'),
11 });

Since Yup and your custom validation function should always output error messages as strings, you'll need to sniff whether your nested error is an array or a string when you go to display it.

So...to display 'Must have friends' and 'Minimum of 3 friends' (our example's array validation constraints)...

Bad

1 // within a `FieldArray`'s render
2 const FriendArrayErrors = errors =>
3   errors.friends ? <div>{errors.friends}</div> : null; // app will crash

Good

1 // within a `FieldArray`'s render
2 const FriendArrayErrors = errors =>
3   typeof errors.friends === 'string' ? <div>{errors.friends}</div> : null;

For the nested field errors, you should assume that no part of the object is defined unless you've checked for it. Thus, you may want to do yourself a favor and make a custom <ErrorMessage /> component that looks like this:

1 import { Field, getIn } from 'formik';
2 
3 const ErrorMessage = ({ name }) => (
4   <Field
5     name={name}
6     render={({ form }) => {
7       const error = getIn(form.errors, name);
8       const touch = getIn(form.touched, name);
9       return touch && error ? error : null;
10     }}
11   />
12 );
13 
14 // Usage
15 <ErrorMessage name="friends[0].name" />; // => null, 'too short', or 'required'

NOTE: In Formik v0.12 / 1.0, a new meta prop may be added to Field and FieldArray that will give you relevant metadata such as error & touch, which will save you from having to use Formik or lodash's getIn or checking if the path is defined on your own.

FieldArray Helpers

The following methods are made available via render props.

push: (obj: any) => void: Add a value to the end of an array
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
insert: (index: number, value: any) => void: Insert an element at a given index into the array
unshift: (value: any) => number: Add an element to the beginning of an array and return its length
remove<T>(index: number): T | undefined: Remove an element at an index of an array and return it
pop<T>(): T | undefined: Remove and return value from the end of the array
replace: (index: number, value: any) => void: Replace a value at the given index into the array

FieldArray render methods

There are three ways to render things with <FieldArray />

<FieldArray name="..." component>
<FieldArray name="..." render>
<FieldArray name="..." children>

`render: (arrayHelpers: ArrayHelpers) => React.ReactNode`

1 import React from 'react';
2 import { Formik, Form, Field, FieldArray } from 'formik'
3 
4 export const FriendList = () => (
5   <div>
6     <h1>Friend List</h1>
7     <Formik
8       initialValues={{ friends: ['jared', 'ian', 'brent'] }}
9       onSubmit={...}
10       render={formikProps => (
11         <FieldArray
12           name="friends"
13           render={({ move, swap, push, insert, unshift, pop }) => (
14             <Form>
15               {/*... use these however you want */}
16             </Form>
17           )}
18         />
19     />
20   </div>
21 );

`component: React.ReactNode`

1 import React from 'react';
2 import { Formik, Form, Field, FieldArray } from 'formik'
3 
4 
5 export const FriendList = () => (
6   <div>
7     <h1>Friend List</h1>
8     <Formik
9       initialValues={{ friends: ['jared', 'ian', 'brent'] }}
10       onSubmit={...}
11       render={formikProps => (
12         <FieldArray
13           name="friends"
14           component={MyDynamicForm}
15         />
16       )}
17     />
18   </div>
19 );
20 
21 
22 // In addition to the array helpers, Formik state and helpers
23 // (values, touched, setXXX, etc) are provided through a `form`
24 // prop
25 export const MyDynamicForm = ({
26   move, swap, push, insert, unshift, pop, form
27 }) => (
28  <Form>
29   {/**  whatever you need to do */}
30  </Form>
31 );

`children: func`

1 import React from 'react';
2 import { Formik, Form, Field, FieldArray } from 'formik'
3 
4 
5 export const FriendList = () => (
6   <div>
7     <h1>Friend List</h1>
8     <Formik
9       initialValues={{ friends: ['jared', 'ian', 'brent'] }}
10       onSubmit={...}
11       render={formikProps => (
12         <FieldArray name="friends">
13           {({ move, swap, push, insert, unshift, pop, form }) => {
14             return (
15               <Form>
16                 {/*... use these however you want */}
17               </Form>
18             );
19           }}
20         </FieldArray>
21       )}
22     />
23   </div>
24 );