<Field />

<Field /> will automagically hook up inputs to Formik. It uses the name attribute to match up with Formik state. <Field /> will default to an HTML <input /> element.

Rendering

There are different ways to render things with <Field>.

• <Field as>
• <Field children>
• <Field render> deprecated in 2.x. Using these will log warning
• <Field component>

as can either be a React component or the name of an HTML element to render. Formik will automagically inject onChange, onBlur, name, and value props of the field designated by the name prop to the (custom) component.

children can either be an array of elements (e.g. <option> in the case of <Field as="select">) or a callback function (a.k.a render prop). The render props are an object containing:

component can either be a React component or the name of an HTML element to render. All additional props will be passed through.

• field: An object containing onChange, onBlur, name, and value of the field (see FieldInputProps)
• form: The Formik bag
• meta: An object containing metadata (i.e. value, touched, error, and initialValue) about the field (see FieldMetaProps)

In Formik 0.9 to 1.x, component and render props could also be used for rendering. These have been deprecated since 2.x. While the code still lives within <Field>, they will show a warning in the console.

Example

1 import React from 'react';
2 import { Field, Form, Formik, FormikProps } from 'formik';
3 
4 const MyInput = ({ field, form, ...props }) => {
5   return <input {...field} {...props} />;
6 };
7 
8 const Example = () => (
9   <div>
10     <h1>My Form</h1>
11     <Formik
12       initialValues={{ email: '', color: 'red', firstName: '', lastName: '' }}
13       onSubmit={(values, actions) => {
14         setTimeout(() => {
15           alert(JSON.stringify(values, null, 2));
16           actions.setSubmitting(false);
17         }, 1000);
18       }}
19     >
20       {(props: FormikProps<any>) => (
21         <Form>
22           <Field type="email" name="email" placeholder="Email" />
23           <Field as="select" name="color">
24             <option value="red">Red</option>
25             <option value="green">Green</option>
26             <option value="blue">Blue</option>
27           </Field>
28 
29           <Field name="lastName">
30             {({
31               field, // { name, value, onChange, onBlur }
32               form: { touched, errors }, // also values, setXXXX, handleXXXX, dirty, isValid, status, etc.
33               meta,
34             }) => (
35               <div>
36                 <input type="text" placeholder="Email" {...field} />
37                 {meta.touched && meta.error && (
38                   <div className="error">{meta.error}</div>
39                 )}
40               </div>
41             )}
42           </Field>
43           <Field name="lastName" placeholder="Doe" component={MyInput} />
44           <button type="submit">Submit</button>
45         </Form>
46       )}
47     </Formik>
48   </div>
49 );

Props

Reference

Props

as

as?: string | React.ComponentType<FieldProps['field']>

Either a React component or the name of an HTML element to render. That is, one of the following:

• input
• select
• textarea
• A valid HTML element name
• A custom React component

Custom React components will be passed onChange, onBlur, name, and value plus any other props passed to directly to <Field>.

Default is 'input' (so an <input> is rendered by default)

1 // Renders an HTML <input> by default
2 <Field name="lastName" placeholder="Last Name"/>
3 
4 // Renders an HTML <select>
5 <Field name="color" as="select" placeholder="Favorite Color">
6   <option value="red">Red</option>
7   <option value="green">Green</option>
8   <option value="blue">Blue</option>
9 </Field>
10 
11 // Renders a CustomInputComponent
12 <Field name="firstName" as={CustomInputComponent} placeholder="First Name"/>
13 
14 const CustomInputComponent = (props) => (
15   <input className="my-custom-input" type="text" {...props} />
16 );

children

children?: React.ReactNode | ((props: FieldProps) => React.ReactNode)

Either JSX elements or callback function. Same as render.

1 // Children can be JSX elements
2 <Field name="color" as="select" placeholder="Favorite Color">
3   <option value="red">Red</option>
4   <option value="green">Green</option>
5   <option value="blue">Blue</option>
6 </Field>
7 
8 // Or a callback function
9 <Field name="firstName">
10 {({ field, form, meta }) => (
11   <div>
12     <input type="text" {...field} placeholder="First Name"/>
13     {meta.touched &&
14       meta.error && <div className="error">{meta.error}</div>}
15   </div>
16 )}
17 </Field>

component

component?: string | React.ComponentType<FieldProps>

Either a React component or the name of an HTML element to render. That is, one of the following:

• input
• select
• textarea
• A custom React component

Custom React components will be passed FieldProps which is same render prop parameters of <Field render> plus any other props passed to directly to <Field>.

Default is 'input' (so an <input> is rendered by default)

1 // Renders an HTML <input> by default
2 <Field name="lastName" placeholder="Last Name"/>
3 
4 // Renders an HTML <select>
5 <Field name="color" component="select" placeholder="Favorite Color">
6   <option value="red">Red</option>
7   <option value="green">Green</option>
8   <option value="blue">Blue</option>
9 </Field>
10 
11 // Renders a CustomInputComponent
12 <Field name="firstName" component={CustomInputComponent} placeholder="First Name"/>
13 
14 const CustomInputComponent = ({
15   field, // { name, value, onChange, onBlur }
16   form: { touched, errors }, // also values, setXXXX, handleXXXX, dirty, isValid, status, etc.
17   ...props
18 }) => (
19   <div>
20     <input type="text" {...field} {...props} />
21     {touched[field.name] &&
22       errors[field.name] && <div className="error">{errors[field.name]}</div>}
23   </div>
24 );

innerRef

innerRef?: (el: React.HTMLElement<any> => void)

When you are not using a custom component and you need to access the underlying DOM node created by Field (e.g. to call focus), pass the callback to the innerRef prop instead.

name

name: string

Required

A field's name in Formik state. To access nested objects or arrays, name can also accept lodash-like dot path like social.facebook or friends[0].firstName

render

render?: (props: FieldProps) => React.ReactNode

Deprecated in 2.x. Use children instead.

A function that returns one or more JSX elements.

1 // Renders an HTML <input> and passes FieldProps field property
2 <Field
3   name="firstName"
4   render={({ field /* { name, value, onChange, onBlur } */ }) => (
5     <input {...field} type="text" placeholder="firstName" />
6   )}
7 />
8 
9 // Renders an HTML <input> and disables it while form is submitting
10 <Field
11   name="lastName"
12   render={({ field, form: { isSubmitting } }) => (
13     <input {...field} disabled={isSubmitting} type="text" placeholder="lastName" />
14   )}
15 />
16 
17 // Renders an HTML <input> with custom error <div> element
18 <Field
19   name="lastName"
20   render={({ field, form: { touched, errors } }) => (
21     <div>
22       <input {...field} type="text" placeholder="lastName" />
23       {touched[field.name] &&
24         errors[field.name] && <div className="error">{errors[field.name]}</div>}
25     </div>
26   )}
27 />

validate

validate?: (value: any) => undefined | string | Promise<any>

You can run independent field-level validations by passing a function to the validate prop. The function will respect the validateOnBlur and validateOnChange config/props specified in the <Field>'s parent <Formik> / withFormik. This function can either be synchronous or asynchronous:

• Sync: if invalid, return a string containing the error message or return undefined.

• Async: return a Promise that throws a string containing the error message. This works like Formik's validate, but instead of returning an errors object, it's just a string.

1 import React from 'react';
2 import { Formik, Form, Field } from 'formik';
3 
4 // Synchronous validation function
5 const validate = value => {
6   let errorMessage;
7   if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(value)) {
8     errorMessage = 'Invalid email address';
9   }
10   return errorMessage;
11 };
12 
13 // Async validation function
14 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
15 
16 const validateAsync = value => {
17   return sleep(2000).then(() => {
18     if (['admin', 'null', 'god'].includes(value)) {
19       throw 'Nice try';
20     }
21   });
22 };
23 
24 // example usage
25 const MyForm = () => (
26   <Formik
27     initialValues={{ email: '', username: '' }}
28     onSubmit={values => alert(JSON.stringify(values, null, 2))}
29   >
30     {({ errors, touched }) => (
31       <Form>
32         <Field validate={validate} name="email" type="email" />
33         {errors.email && touched.email ? <div>{errors.email}</div> : null}
34         <Field validate={validateAsync} name="username" />
35         {errors.username && touched.username ? (
36           <div>{errors.username}</div>
37         ) : null}
38         <button type="submit">Submit</button>
39       </Form>
40     )}
41   </Formik>
42 );

Note: To allow for i18n libraries, the TypeScript typings for validate are slightly relaxed and allow you to return a Function (e.g. i18n('invalid')).