useField()

useField is a custom React hook that will automagically help you hook up inputs to Formik. You can and should use it to build your own custom input primitives. There are 2 ways to use it.

Example

1 import React from 'react';
2 import { useField, Form, FormikProps, Formik } from 'formik';
3 
4 interface Values {
5   firstName: string;
6   lastName: string;
7   email: string;
8 }
9 
10 const MyTextField = ({ label, ...props }) => {
11   const [field, meta, helpers] = useField(props);
12   return (
13     <>
14       <label>
15         {label}
16         <input {...field} {...props} />
17       </label>
18       {meta.touched && meta.error ? (
19         <div className='error'>{meta.error}</div>
20       ) : null}
21     </>
22   );
23 };
24 
25 const Example = () => (
26   <div>
27     <h1>My Form</h1>
28     <Formik
29       initialValues={{
30         email: '',
31         firstName: 'red',
32         lastName: '',
33       }}
34       onSubmit={(values, actions) => {
35         setTimeout(() => {
36           alert(JSON.stringify(values, null, 2));
37           actions.setSubmitting(false);
38         }, 1000);
39       }}
40     >
41       {(props: FormikProps<Values>) => (
42         <Form>
43           <MyTextField name="firstName" type="text" label="First Name" />
44           <MyTextField name="lastName" type="text" label="Last Name" />
45           <MyTextField name="email" type="email" label="Email" />
46           <button type="submit">Submit</button>
47         </Form>
48       )}
49     </Formik>
50   </div>
51 );

Reference

useField<Value = any>(name: string | FieldAttributes<Val>): [FieldInputProps<Value>, FieldMetaProps<Value>, FieldHelperProps]

A custom React Hook that returns a 3-tuple (an array with three elements) containing FieldProps, FieldMetaProps and FieldHelperProps. It accepts either a string of a field name or an object as an argument. The object must at least contain a name key. This object should be identical to the props that you would pass to <Field> and the values and functions in FieldProps will mimic the behavior of <Field> exactly. This is useful, and generally preferred, since it allows you to take advantage of Formik's checkbox, radio, and multiple select behavior when the object contains the relevant key/values (e.g. type: 'checkbox', multiple: true, etc.).

FieldMetaProps contains computed values about the field which can be used to style or otherwise change the field. FieldHelperProps contains helper functions that allow you to imperatively change a field's values.

1 import React from 'react';
2 import { useField } from 'formik';
3 
4 function MyTextField(props) {
5   // this will return field props for an <input />
6   const [field, meta, helpers] = useField(props.name);
7   return (
8     <>
9       <input {...field} {...props} />
10       {meta.error && meta.touched && <div>{meta.error}</div>}
11     </>
12   );
13 }
14 
15 function MyInput(props) {
16   // this will return field exactly like <Field>{({ field }) => ... }</Field>
17   const [field, meta] = useField(props);
18   return (
19     <>
20       <input {...field} {...props} />
21       {meta.error && meta.touched && <div>{meta.error}</div>}
22     </>
23   );
24 }
25 
26 function MyOtherComponent(props) {
27   // This isn't an input, so instead of using the values in 'field' directly,
28   // we'll use 'meta' and 'helpers'.
29   const [field, meta, helpers] = useField(props.name);
30 
31   const { value } = meta;
32   const { setValue } = helpers;
33 
34   const isSelected = v => (v === value ? 'selected' : '');
35 
36   return (
37     <div className='itemsPerPage'>
38       <button onClick={() => setValue(5)} className={isSelected(5)}>
39         5
40       </button>
41       <button onClick={() => setValue(10)} className={isSelected(10)}>
42         10
43       </button>
44       <button onClick={() => setValue(25)} className={isSelected(25)}>
45         25
46       </button>
47     </div>
48   );
49 }

FieldInputProps<Value>

An object that contains:

• name: string - The name of the field
• checked?: boolean - Whether or not the input is checked, this is only defined if useField is passed an object with a name, type: 'checkbox' or type: 'radio'.
• onBlur: () => void - A blur event handler
• onChange: (e: React.ChangeEvent<any>) => void - A change event handler
• value: Value - The field's value (plucked out of values) or, if it is a checkbox or radio input, then potentially the value passed into useField.
• multiple?: boolean - Whether or not the multiple values can be selected. This is only ever defined when useField is passed an object with multiple: true

FieldMetaProps<Value>

An object that contains relevant computed metadata about a field. More specifically,

• error?: string - The field's error message (plucked out of errors)
• initialError?: string - The field's initial error if the field is present in initialErrors (plucked out of initialErrors)
• initialTouched: boolean - The field's initial value if the field is present in initialTouched (plucked out of initialTouched)
• initialValue?: Value - The field's initial value if the field is given a value in initialValues (plucked out of initialValues)
• touched: boolean - Whether the field has been visited (plucked out of touched)
• value: any - The field's value (plucked out of values)

FieldHelperProps

An object that contains helper functions which you can use to imperatively change the value, error value or touched status for the field in question. This is useful for components which need to change a field's status directly, without triggering change or blur events.

• setValue(value: any, shouldValidate?: boolean): void - A function to change the field's value. Calling this will trigger validation to run if validateOnChange is set to true (which it is by default). You can also explicitly prevent/skip validation by passing a second argument as false.
• setTouched(value: boolean, shouldValidate?: boolean): void - A function to change the field's touched status. Calling this will trigger validation to run if validateOnBlur is set to true (which it is by default). You can also explicitly prevent/skip validation by passing a second argument as false.
• setError(value: any): void - A function to change the field's error value