Migrating from v1.x to v2.x

Breaking Changes

Minimum Requirements

• Since Formik 2 is built on top of React Hooks, you must be on React 16.8.x or higher
• Since Formik 2 uses the unknown type, you must be on TypeScript 3.0 or higher (if you use TypeScript)

There are a few breaking changes in Formik 2.x. Luckily, these probably won't impact many people:

resetForm

With Formik 2, we introduced the new props for more initial state: initialErrors, initialTouched, initialStatus. Therefore, resetForm's signature has changed. Instead of optionally accepting just the next initial values of the form. It now optionally accepts the partial next initial state of Formik.

v1

1 // Reset to `initialValues`
2 formik.resetForm();
3 // Reset form and set the next `initialValues` of the form
4 formik.resetForm({ name: '', email: '' });

v2

1 // Reset the form. This will set the next initial state of
2 // Formik to the `initialValues`, `initialErrors`, `initialTouched`,
3 // `initialStatus` props.
4 formik.resetForm();
5 
6 // Reset the form back to `initialXXXX` but change next
7 // `initialValues` to a custom value
8 formik.resetForm({
9   values: { name: 'Custom initial values', email: '' },
10 });
11 
12 // Reset form back to `initialXXXX`, but change next `initialValues`
13 // and `initialErrors` of the form
14 formik.resetForm({
15   values: { name: '', email: '' },
16   errors: { name: 'Something special' },
17 });
18 
19 // Reset form back to `initialXXXX`, but change next `initialStatus` to 'Foo'
20 formik.resetForm({
21   status: 'Foo',
22 });

setError

This method has been deprecated for a while with a warning in v1.x releases. It's fully removed in v2. Please use Formik's setStatus(status) instead. It works identically. Note: this is/was not setErrors (plural) which is still around.

validate

As you may know, you can return a Promise of a validation error from validate. In 1.x, it didn't matter if this promise is resolved or rejected as in both cases the payload of the promise was interpreted as the validation error. In 2.x, rejection will be interpreted as an actual exception and it won't update the form error state. Any validation function that returns a rejected promise of errors needs to be adjusted to return a resolved promise of errors instead.

ref

Currently, you can't attach a ref to Formik using the ref prop. However, you still can get around this issue using the prop innerRef. We have some WIP #2208 to instead use React.forwardRef.

isValid

This property does not take the value of dirty into account anymore. This means that if you want to disable a submit button when the form is not dirty (i.e. on first render and when values are unchanged), you have to explicitly check for it.

1 <button disabled={!isValid || !dirty} type="submit">
2   Submit
3 </button>

Typescript changes

FormikActions

FormikActions has been renamed to FormikHelpers It should be a straightforward change to import or alias the type

v1

 import { FormikActions } from 'formik';

v2

 import { FormikHelpers as FormikActions } from 'formik';

FieldProps

FieldProps now accepts two generic type parameters. Both parameters are optional, but FormValues has been moved from the first to the second parameter.

v1

 type Props = FieldProps<FormValues>;

v2

 type Props = FieldProps<FieldValue, FormValues>;

What's New?

Checkboxes and Select multiple

Similarly to Angular, Vue, or Svelte, Formik 2 "fixes" React checkboxes and multi-selects with built-in array binding and boolean behavior. This was one of the most confusing things for people in Formik 1.x.

1 import React from 'react';
2 import { Formik, Field, Form } from 'formik';
3 import { Debug } from './Debug';
4 
5 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
6 
7 const CheckboxExample = () => (
8   <div>
9     <h1>Checkboxes</h1>
10     <p>
11       This example demonstrates how to properly create checkboxes with Formik.
12     </p>
13     <Formik
14       initialValues={{
15         isAwesome: false,
16         terms: false,
17         newsletter: false,
18         jobType: ['designer'],
19         location: [],
20       }}
21       onSubmit={async values => {
22         await sleep(1000);
23         alert(JSON.stringify(values, null, 2));
24       }}
25     >
26       {({ isSubmitting, getFieldProps, handleChange, handleBlur, values }) => (
27         <Form>
28           {/* 
29             This first checkbox will result in a boolean value being stored.
30           */}
31           <div className="label">Basic Info</div>
32           <label>
33             <Field type="checkbox" name="isAwesome" />
34             Are you awesome?
35           </label>
36           {/* 
37             Multiple checkboxes with the same name attribute, but different
38             value attributes will be considered a "checkbox group". Formik will automagically
39             bind the checked values to a single array for your benefit. All the add and remove
40             logic will be taken care of for you.
41           */}
42           <div className="label">
43             What best describes you? (check all that apply)
44           </div>
45           <label>
46             <Field type="checkbox" name="jobType" value="designer" />
47             Designer
48           </label>
49           <label>
50             <Field type="checkbox" name="jobType" value="developer" />
51             Developer
52           </label>
53           <label>
54             <Field type="checkbox" name="jobType" value="product" />
55             Product Manager
56           </label>
57           {/*
58            You do not _need_ to use <Field>/useField to get this behavior, 
59            using handleChange, handleBlur, and values works as well. 
60           */}
61           <label>
62             <input
63               type="checkbox"
64               name="jobType"
65               value="founder"
66               checked={values.jobType.includes('founder')}
67               onChange={handleChange}
68               onBlur={handleBlur}
69             />
70             CEO / Founder
71           </label>
72 
73           {/* 
74            The <select> element will also behave the same way if 
75            you pass `multiple` prop to it. 
76           */}
77           <label htmlFor="location">Where do you work?</label>
78           <Field
79             component="select"
80             id="location"
81             name="location"
82             multiple={true}
83           >
84             <option value="NY">New York</option>
85             <option value="SF">San Francisco</option>
86             <option value="CH">Chicago</option>
87             <option value="OTHER">Other</option>
88           </Field>
89           <label>
90             <Field type="checkbox" name="terms" />I accept the terms and
91             conditions.
92           </label>
93           {/* Here's how you can use a checkbox to show / hide another field */}
94           {!!values.terms ? (
95             <div>
96               <label>
97                 <Field type="checkbox" name="newsletter" />
98                 Send me the newsletter <em style={{ color: 'rebeccapurple' }}>
99                   (This is only shown if terms = true)
100                 </em>
101               </label>
102             </div>
103           ) : null}
104           <button type="submit" disabled={isSubmitting}>
105             Submit
106           </button>
107           <Debug />
108         </Form>
109       )}
110     </Formik>
111   </div>
112 );
113 
114 export default CheckboxExample;

useField()

Just what you think, it's like <Field>, but with a hook. See docs for usage.

useFormikContext()

A hook that is equivalent to connect().

<Field as>

<Field/> now accepts a prop called as which will inject onChange, onBlur, value etc. directly through to the component or string. This is useful for folks using Emotion or Styled components as they no longer need to clean up component's render props in a wrapped function.

1 // <input className="form-input" placeholder="Jane"  />
2 <Field name="firstName" className="form-input" placeholder="Jane" />
3 
4 // <textarea className="form-textarea"/></textarea>
5 <Field name="message" as="textarea"  className="form-textarea"/>
6 
7 // <select className="my-select"/>
8 <Field name="colors" as="select" className="my-select">
9   <option value="red">Red</option>
10   <option value="green">Green</option>
11   <option value="blue">Blue</option>
12 </Field>
13 
14 // with styled-components/emotion
15 const MyStyledInput = styled.input`
16   padding: .5em;
17   border: 1px solid #eee;
18   /* ... */
19 `
20 const MyStyledTextarea = MyStyledInput.withComponent('textarea');
21 
22 // <input className="czx_123" placeholder="google.com"  />
23 <Field name="website" as={MyStyledInput} placeholder="google.com"/>
24 
25 // <textarea placeholder="Post a message..." rows={5}></textarea>
26 <Field name="message" as={MyStyledTextArea} placeholder="Post a message.." rows={4}/>

getFieldProps(nameOrProps)

There are two useful additions to FormikProps, getFieldProps and getFieldMeta. These are Kent C. Dodds-esque prop getters that can be useful if you love prop drilling, are not using the context-based API's, or if you are building a custom useField.

1 export interface FieldInputProps<Value> {
2   /** Value of the field */
3   value: Value;
4   /** Name of the field */
5   name: string;
6   /** Multiple select? */
7   multiple?: boolean;
8   /** Is the field checked? */
9   checked?: boolean;
10   /** Change event handler */
11   onChange: FormikHandlers['handleChange'];
12   /** Blur event handler */
13   onBlur: FormikHandlers['handleBlur'];
14 }

getFieldMeta(name)

Given a name it will return an object:

1 export interface FieldMetaProps<Value> {
2   /** Value of the field */
3   value: Value;
4   /** Error message of the field */
5   error?: string;
6   /** Has the field been visited? */
7   touched: boolean;
8   /** Initial value of the field */
9   initialValue?: Value;
10   /** Initial touched state of the field */
11   initialTouched: boolean;
12   /** Initial error message of the field */
13   initialError?: string;
14 }

Misc

• FormikContext is now exported
• validateOnMount?: boolean = false
• initialErrors, initialTouched, initialStatus have been added

Deprecation Warnings

All render props have been deprecated with a console warning.

For <Field>, <FastField>, <Formik>,<FieldArray>, the render prop has been deprecated with a warning as it will be removed in future versions. Instead, use a child callback function. This deprecation is meant to parallel React Context Consumer's usage.

1 - <Field name="firstName" render={props => ....} />
2 + <Field name="firstName">{props => ... }</Field>