Formik is a popular open-source library for building forms in React and React Native. It helps with handling form state, validation, and submission. Formik provides a simple and efficient way to create controlled form components with less boilerplate code.
Form State Management
Formik simplifies form state management by providing 'initialValues' to set up the form state and 'onSubmit' to handle form submission.
{"<Formik initialValues={{ name: '' }} onSubmit={(values) => { console.log(values); }}><Form><Field name='name' type='text' /><button type='submit'>Submit</button></Form></Formik>"}Validation and Error Handling
Formik provides a 'validate' function to define custom validation logic and uses 'ErrorMessage' to display validation errors.
{"<Formik initialValues={{ email: '' }} validate={values => { const errors = {}; if (!values.email) { errors.email = 'Required'; } else if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(values.email)) { errors.email = 'Invalid email address'; } return errors; }} onSubmit={(values, { setSubmitting }) => { setTimeout(() => { alert(JSON.stringify(values, null, 2)); setSubmitting(false); }, 400); }}><Form><Field name='email' type='email' /><ErrorMessage name='email' component='div' /><button type='submit'>Submit</button></Form></Formik>"}Integration with Yup for Schema Validation
Formik can be integrated with Yup, a schema builder for value parsing and validation, to simplify form validation using a schema.
{"<Formik initialValues={{ email: '' }} validationSchema={Yup.object({ email: Yup.string().email('Invalid email address').required('Required'), })} onSubmit={(values, { setSubmitting }) => { setTimeout(() => { alert(JSON.stringify(values, null, 2)); setSubmitting(false); }, 400); }}><Form><Field name='email' type='email' /><ErrorMessage name='email' /><button type='submit'>Submit</button></Form></Formik>"}Custom Input Components
Formik allows the use of custom input components with the 'as' prop in the 'Field' component, enabling the creation of reusable form elements.
{"<Formik initialValues={{ name: '' }} onSubmit={(values) => { console.log(values); }}><Form><Field name='name' as={MyCustomInput} /><button type='submit'>Submit</button></Form></Formik>"}React Hook Form is a library for managing forms in React. It uses hooks for form state management and is optimized for performance by minimizing the number of re-renders. Compared to Formik, React Hook Form is often considered faster due to its leaner API and focus on reducing re-renders.
Redux Form leverages Redux for form state management. It integrates tightly with Redux and allows form state to be stored in the Redux store. Compared to Formik, Redux Form is more suitable for applications that already use Redux and require complex form state management across multiple components.
Final Form is a framework-agnostic form library that can be used with React via 'react-final-form'. It focuses on performance and flexibility, offering subscription-based form state management. Compared to Formik, Final Form provides more fine-grained control over form state updates and subscriptions.
Let's face it, forms are really verbose in React. To make matters worse, most form helpers do wayyyy too much magic and often have a significant performance cost associated with them. Formik is a small library that helps you with the 3 most annoying parts:
By colocating all of the above in one place, Formik will keep things organized--making testing, refactoring, and reasoning about your forms a breeze.
I (@jaredpalmer) wrote Formik while building a large internal administrative dashboard with @eonwhite. With around ~30 unique forms, it quickly became obvious that we could benefit by standardizing not just our input components but also the way in which data flowed through our forms.
By now, you might be thinking, "Why didn't you just use Redux-Form?" Good question.
My goal with Formik was to create a scalable, performant, form helper with a minimal API that does the really really annoying stuff, and leaves the rest up to you.
Formik started by expanding on this little higher order component by Brent Jackson, some naming conventions from Redux-Form, and (most recently) the render props approach popularized by React-Motion and React-Router 4. Whether you have used any of the above or not, Formik only takes a few minutes to get started with.
Add Formik to your project.
npm i formik --save
You can also try before you buy with this demo of Formik on CodeSandbox.io
Formik keeps track of your form's state and then exposes it plus a few reusable
methods and event handlers (handleChange, handleBlur, and handleSubmit) to
your form via props. handleChange and handleBlur work exactly as
expected--they use a name or id attribute to figure out which field to
update.
There are two ways to use Formik:
withFormik(): A Higher-order Component (HoC) that accepts a configuration
object<Formik />: A React component with a render propBoth do exactly the same thing and share the same internal implementation. They just differ in their respective style....
// Higher Order Component
import React from 'react';
import { withFormik } from 'formik';
// Our inner form component which receives our form's state and updater methods as props
const InnerForm = ({
values,
errors,
touched,
handleChange,
handleBlur,
handleSubmit,
isSubmitting,
}) => (
<form onSubmit={handleSubmit}>
<input
type="email"
name="email"
onChange={handleChange}
onBlur={handleBlur}
value={values.email}
/>
{touched.email && errors.email && <div>{errors.email}</div>}
<input
type="password"
name="password"
onChange={handleChange}
onBlur={handleBlur}
value={values.password}
/>
{touched.password && errors.password && <div>{errors.password}</div>}
<button type="submit" disabled={isSubmitting}>
Submit
</button>
</form>
);
// Wrap our form with the using withFormik HoC
const MyForm = withFormik({
// Transform outer props into form values
mapPropsToValues: props => ({ email: '', password: '' }),
// Add a custom validation function (this can be async too!)
validate: (values, props) => {
const errors = {};
if (!values.email) {
errors.email = 'Required';
} else if (
!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(values.email)
) {
errors.email = 'Invalid email address';
}
return errors;
},
// Submission handler
handleSubmit: (
values,
{
props,
setSubmitting,
setErrors /* setValues, setStatus, and other goodies */,
}
) => {
LoginToMyApp(values).then(
user => {
setSubmitting(false);
// do whatevs...
// props.updateUser(user)
},
errors => {
setSubmitting(false);
// Maybe even transform your API's errors into the same shape as Formik's!
setErrors(transformMyApiErrors(errors));
}
);
},
})(InnerForm);
// Use <MyForm /> anywhere
const Basic = () => (
<div>
<h1>My Form</h1>
<p>This can be anywhere in your application</p>
<MyForm />
</div>
);
export default Basic;
// Render Prop
import React from 'react';
import { Formik } from 'formik';
const Basic = () => (
<div>
<h1>My Form</h1>
<p>This can be anywhere in your application</p>
{/*
The benefit of the render prop approach is that you have full access to React's
state, props, and composition model. Thus there is no need to map outer props
to values...you can just set the initial values, and if they depend on props / state
then--boom--you can directly access to props / state.
The render prop accepts your inner form component, which you can define separately or inline
totally up to you:
- `<Formik render={props => <form>...</form>}>`
- `<Formik component={InnerForm}>`
- `<Formik>{props => <form>...</form>}</Formik>` (identical to as render, just written differently)
*/}
<Formik
initialValues={{
email: '',
password: '',
}}
validate={values => {
// same as above, but feel free to move this into a class method now.
let errors = {};
if (!values.email) {
errors.email = 'Required';
} else if (
!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(values.email)
) {
errors.email = 'Invalid email address';
}
return errors;
}}
onSubmit={(
values,
{ setSubmitting, setErrors /* setValues and other goodies */ }
) => {
LoginToMyApp(values).then(
user => {
setSubmitting(false);
// do whatevs...
// props.updateUser(user)
},
errors => {
setSubmitting(false);
// Maybe transform your API's errors into the same shape as Formik's
setErrors(transformMyApiErrors(errors));
}
);
}}
render={({
values,
errors,
touched,
handleChange,
handleBlur,
handleSubmit,
isSubmitting,
}) => (
<form onSubmit={handleSubmit}>
<input
type="email"
name="email"
onChange={handleChange}
onBlur={handleBlur}
value={values.email}
/>
{touched.email && errors.email && <div>{errors.email}</div>}
<input
type="password"
name="password"
onChange={handleChange}
onBlur={handleBlur}
value={values.password}
/>
{touched.password && errors.password && <div>{errors.password}</div>}
<button type="submit" disabled={isSubmitting}>
Submit
</button>
</form>
)}
/>
</div>
);
export default Basic;
As you can see above, validation is left up to you. Feel free to write your own
validators or use a 3rd party library. Personally, I use
Yup for object schema validation. It has an
API that's pretty similar Joi /
React PropTypes but is small enough
for the browser and fast enough for runtime usage. Because I :heart: Yup sooo
much, Formik has a special config option / prop for Yup called
validationSchema which will automatically transform Yup's validation errors
into a pretty object whose keys match values and touched. Anyways, you
can install Yup from npm...
npm install yup --save
** Table of Contents **
<Formik />
dirty: booleanerrors: { [field: string]: string }handleBlur: (e: any) => voidhandleChange: (e: React.ChangeEvent<any>) => voidhandleReset: () => voidhandleSubmit: (e: React.FormEvent<HTMLFormEvent>) => voidisSubmitting: booleanisValid: booleanresetForm: (nextValues?: Values) => voidsetErrors: (fields: { [field: string]: string }) => voidsetFieldError: (field: string, errorMsg: string) => voidsetFieldTouched: (field: string, isTouched: boolean, shouldValidate?: boolean) => voidsetFieldValue: (field: string, value: any, shouldValidate?: boolean) => voidsetStatus: (status?: any) => voidsetSubmitting: (isSubmitting: boolean) => voidsetTouched: (fields: { [field: string]: boolean }) => voidsetValues: (fields: { [field: string]: any }) => voidstatus?: anytouched: { [field: string]: boolean }values: { [field: string]: any }validateForm: (values?: any) => voidcomponentrender: (props: FormikProps<Values>) => ReactNodechildren: funcenableReinitialize?: booleanisInitialValid?: booleaninitialValues?: ValuesonReset?: (values: Values, formikBag: FormikBag) => voidonSubmit: (values: Values, formikBag: FormikBag) => voidvalidate?: (values: Values) => FormikError<Values> | Promise<any>validateOnBlur?: booleanvalidateOnChange?: booleanvalidationSchema?: Schema | (() => Schema)<Field />
<FieldArray/>
<Form />withFormik(options)
options
displayName?: stringenableReinitialize?: booleanhandleSubmit: (values: Values, formikBag: FormikBag) => void
isInitialValid?: boolean | (props: Props) => booleanmapPropsToValues?: (props: Props) => Valuesvalidate?: (values: Values, props: Props) => FormikError<Values> | Promise<any>validateOnBlur?: booleanvalidateOnChange?: booleanvalidationSchema?: Schema | ((props: Props) => Schema)Imagine you want to build a form that lets you edit user data. However, your user API has nested objects like so.
{
id: string,
email: string,
social: {
facebook: string,
twitter: string,
// ...
}
}
When we are done we want our dialog to accept just a user, updateUser, and
onClose props.
// User.js
import React from 'react';
import Dialog from 'MySuperDialog';
import EditUserForm from './EditUserForm';
import { Formik } from 'formik';
const EditUserDialog = ({ user, updateUser, onClose }) => {
return (
<Dialog onClose={onClose}>
<h1>Edit User</h1>
<Formik
initialValues={user /** { email, social } */}
onSubmit={(values, actions) => {
CallMyApi(user.id, values).then(
updatedUser => {
actions.setSubmitting(false);
updateUser(updatedUser), onClose();
},
error => {
actions.setSubmitting(false);
actions.setErrors(transformMyAPIErrorToAnObject(error));
}
);
}}
render={({
values,
errors,
touched,
handleBlur,
handleChange,
handleSubmit,
isSubmitting,
}) => (
<form onSubmit={handleSubmit}>
<input
type="email"
name="email"
onChange={handleChange}
onBlur={handleBlur}
value={values.email}
/>
{errors.email && touched.email && <div>{errors.email}</div>}
<input
type="text"
name="social.facebook"
onChange={handleChange}
onBlur={handleBlur}
value={values.social.facebook}
/>
{errors.social.facebook &&
touched.facebook && <div>{errors.social.facebook}</div>}
<input
type="text"
name="social.twitter"
onChange={handleChange}
onBlur={handleBlur}
value={values.social.twitter}
/>
{errors.social.twitter &&
touched.twitter && <div>{errors.social.twitter}</div>}
<button type="submit" disabled={isSubmitting}>
Submit
</button>
</form>
)}
/>
</Dialog>
);
};
To make writing forms less verbose. Formik comes with a few helpers to save you key strokes.
<Field><Form/>This is the exact same form as before, but written with <Form/> and
<Field/>:
// EditUserDialog.js
import React from 'react';
import Dialog from 'MySuperDialog';
import EditUserForm from './EditUserForm';
import { Formik, Field, Form } from 'formik';
const EditUserDialog = ({ user, updateUser, onClose }) => {
return (
<Dialog onClose={onClose}>
<h1>Edit User</h1>
<Formik
initialValues={user /** { email, social } */}
onSubmit={(values, actions) => {
CallMyApi(user.id, values).then(
updatedUser => {
actions.setSubmitting(false);
updateUser(updatedUser), onClose();
},
error => {
actions.setSubmitting(false);
actions.setErrors(transformMyAPIErrorToAnObject(error));
}
);
}}
render={({ errors, touched, isSubmitting }) => (
<Form>
<Field type="email" name="email" />
{errors.email && touched.social.email && <div>{errors.email}</div>}
<Field type="text" name="social.facebook" />
{errors.social.facebook &&
touched.social.facebook && <div>{errors.social.facebook}</div>}
<Field type="text" name="social.twitter" />
{errors.social.twitter &&
touched.social.twitter && <div>{errors.social.twitter}</div>}
<button type="submit" disabled={isSubmitting}>
Submit
</button>
</Form>
)}
/>
</Dialog>
);
};
Formik is 100% compatible with React Native and React Native Web. However, because of differences between ReactDOM's and React Native's handling of forms and text input, there are two differences to be aware of. This section will walk you through them and what I consider to be best practices.
Before going any further, here's a super minimal gist of how to use Formik with React Native that demonstrates the key differences:
// Formik x React Native example
import React from 'react';
import { Button, TextInput, View } from 'react-native';
import { withFormik } from 'formik';
const enhancer = withFormik({
/*...*/
});
const MyReactNativeForm = props => (
<View>
<TextInput
onChangeText={text => props.setFieldValue('email', text)}
value={props.values.email}
/>
<Button onPress={props.handleSubmit} title="Submit" /> //
</View>
);
export default enhancer(MyReactNativeForm);
As you can see above, the notable differences between using Formik with React DOM and React Native are:
props.handleSubmit is passed to a <Button onPress={...}/>
instead of HTML <form onSubmit={...}/> component (since there is no
<form/> element in React Native).<TextInput /> uses Formik's props.setFieldValue instead of
props.handleChange. To understand why, see the discussion below.setFieldValue instead of handleChange?'cuz handleChange will not work in React Native...
import { Button, TextInput, View } from 'react-native';
import { Formik } from 'formik';
const MyReactNativeForm = props => (
<View>
<Formik
onSubmit={(values, actions) => {
setTimeout(() => {
console.log(JSON.stringify(values, null, 2));
actions.setSubmitting(false);
}, 1000);
}}
render={props => (
<View>
<TextInput
name="email"
onChangeText={props.handleChange} // this WILL NOT WORK IN RN
value={props.values.email}
/>
<Button onPress={props.handleSubmit} />
</View>
)}
/>
</View>
);
The reason is that Formik's handleChange function expects its first argument
to be synthetic DOM event where the event.target is the DOM input element and
event.target.id or event.target.name matches the field to be updated.
Without this, handleChange will do nothing.
In React Native, neither
<TextInput />'s
onChange
nor
onChangeText
callbacks pass such an event or one like it to its callback. Instead, they do
the following (emphasis added):
onChange?: function
Callback that is called when the text input's text changes.
onChangeText?: function
Callback that is called when the text input's text changes. Changed text is passed as an argument to the callback handler.
However, Formik works just fine if you use props.setFieldValue!
Philisophically, just treat React Native's <TextInput/> the same way you would
any other 3rd party custom input element.
In conclusion, the following WILL work in React Native:
// ...
// this works.
export const MyReactNativeForm = props => (
<View>
<TextInput
onChangeText={text => props.setFieldValue('email', text)}
value={props.values.email}
/>
<Button onPress={props.handleSubmit} />
</View>
);
// ...
If for any reason you wish to avoid creating new functions on each render, I
suggest treating React Native's <TextInput/> as if it were another 3rd party
custom input element:
props.setFieldValue instead of
props.handleChangesetFieldValue as (in this case we'll match the React Native TextInput API
and call it this.props.onChangeText for parity).// FormikReactNativeTextInput.js
import * as React from 'react';
import { TextInput } from 'react-native';
export default class FormikReactNativeTextInput extends React.Component {
handleChange = (value: string) => {
// remember that onChangeText will be Formik's setFieldValue
this.props.onChangeText(this.props.name, value);
};
render() {
// we want to pass through all the props except for onChangeText
const { onChangeText, ...otherProps } = this.props;
return (
<TextInput
onChangeText={this.handleChange}
{...otherProps} // IRL, you should be more explicit when using TS
/>
);
}
}
Then you could just use this custom input as follows:
// MyReactNativeForm.js
import { View, Button } from 'react-native';
import TextInput from './FormikReactNativeTextInput';
import { Formik } from 'formik';
const MyReactNativeForm = props => (
<View>
<Formik
onSubmit={(values, actions) => {
setTimeout(() => {
console.log(JSON.stringify(values, null, 2));
actions.setSubmitting(false);
}, 1000);
}}
render={props => (
<View>
<TextInput
name="email"
onChangeText={props.setFieldValue}
value={props.values.email}
/>
<Button title="submit" onPress={props.handleSubmit} />
</View>
)}
/>
</View>
);
export default MyReactNativeForm;
The Formik source code is written in TypeScript, so you can rest assured that
types will always be up to date. As a mental model, Formik's types are very
similar to React Router 4's <Route>.
<Formik /> and <Field/>)import * as React from 'react';
import { Formik, FormikProps, Form, Field, FieldProps } from 'formik';
interface MyFormValues {
firstName: string;
}
export const MyApp: React.SFC<{} /* whatever */> = () => {
return (
<div>
<h1>My Example</h1>
<Formik
initialValues={{ firstName: '' }}
onSubmit={(values: MyFormValues) => alert(JSON.stringify(values))}
render={(formikBag: FormikProps<MyFormValues>) => (
<Form>
<Field
name="firstName"
render={({ field, form }: FieldProps<MyFormValues>) => (
<div>
<input type="text" {...field} placeholder="First Name" />
{form.touched.firstName &&
form.errors.firstName &&
form.errors.firstName}
</div>
)}
/>
</Form>
)}
/>
</div>
);
};
withFormik()import React from 'react';
import Yup from 'yup';
import { withFormik, FormikProps, FormikErrors, Form, Field } from 'formik';
// Shape of form values
interface FormValues {
email: string;
password: string;
}
interface OtherProps {
message: string;
}
// You may see / user InjectedFormikProps<OtherProps, FormValues> instead of what comes below. They are the same--InjectedFormikProps was artifact of when Formik only exported an HOC. It is also less flexible as it MUST wrap all props (it passes them through).
const InnerForm = (props: OtherProps & FormikProps<FormValues>) => {
const { touched, errors, isSubmitting, message } = props;
return (
<Form>
<h1>{message}</h1>
<Field type="email" name="email" />
{touched.email && errors.email && <div>{errors.email}</div>}
<Field type="password" name="password" />
{touched.password && errors.password && <div>{errors.password}</div>}
<button type="submit" disabled={isSubmitting}>
Submit
</button>
</Form>
);
};
// The type of props MyForm receives
interface MyFormProps {
initialEmail?: string;
message: string; // if this passed all the way through you might do this or make a union type
}
// Wrap our form with the using withFormik HoC
const MyForm = withFormik<MyFormProps, FormValues>({
// Transform outer props into form values
mapPropsToValues: props => {
return {
email: props.initialEmail || '',
password: '',
};
},
// Add a custom validation function (this can be async too!)
validate: (values: FormValues) => {
let errors: FormikErrors = {};
if (!values.email) {
errors.email = 'Required';
} else if (!isValidEmail(values.email)) {
errors.email = 'Invalid email address';
}
return errors;
},
handleSubmit: values => {
// do submitting things
},
})(InnerForm);
// Use <MyForm /> anywhere
const Basic = () => (
<div>
<h1>My App</h1>
<p>This can be anywhere in your application</p>
<MyForm message="Sign up" />
</div>
);
export default Basic;
<Formik /><Formik> is a component that helps you with building forms. It uses a render
props pattern made popular by libraries like React Motion and React Router.
import React from 'react';
import { Formik } from 'formik';
const BasicExample = () => (
<div>
<h1>My Form</h1>
<Formik
initialValues={{ name: 'jared' }}
onSubmit={(values, actions) => {
setTimeout(() => {
alert(JSON.stringify(values, null, 2));
actions.setSubmitting(false);
}, 1000);
}}
render={props => (
<form onSubmit={props.handleSubmit}>
<input
type="text"
onChange={props.handleChange}
onBlur={props.handleBlur}
value={props.values.name}
name="name"
/>
{props.errors.name && <div id="feedback">{props.errors.name}</div>}
<button type="submit">Submit</button>
</form>
)}
/>
</div>
);
There are three ways to render things with <Formik/>
<Formik component><Formik render><Formik children>All three render methods will be passed the same props:
dirty: booleanReturns true if values are not deeply equal from initial values, false otherwise.
dirty is a readonly computed property and should not be mutated directly.
errors: { [field: string]: string }Form validation errors. Should match the shape of your form's values defined
in initialValues. If you are using validationSchema (which you should be),
keys and shape will match your schema exactly. Internally, Formik transforms raw
Yup validation errors
on your behalf. If you are using validate, then that function will determine
the errors objects shape.
handleBlur: (e: any) => voidonBlur event handler. Useful for when you need to track whether an input has
been touched or not. This should be passed to <input onBlur={handleBlur} ... />
DOM-only. Use setFieldTouched in React Native.
handleChange: (e: React.ChangeEvent<any>) => voidGeneral input change event handler. This will update the values[key] where
key is the event-emitting input's name attribute. If the name attribute is
not present, handleChange will look for an input's id attribute. Note:
"input" here means all HTML inputs.
DOM-only. Use setFieldValue in React Native.
handleReset: () => voidReset handler. Will reset the form to its initial state. This should be passed
to <button onClick={handleReset}>...</button>
handleSubmit: (e: React.FormEvent<HTMLFormEvent>) => voidSubmit handler. This should be passed to <form onSubmit={props.handleSubmit}>...</form>
isSubmitting: booleanSubmitting state. Either true or false. Formik will set this to true on
your behalf before calling handleSubmit to reduce boilerplate.
isValid: booleanReturns true if the there are no errors, or the result of
isInitialValid the form if is in "pristine" condition (i.e. not dirty)).
resetForm: (nextValues?: Values) => voidImperatively reset the form. This will clear errors and touched, set
isSubmitting to false and rerun mapPropsToValues with the current
WrappedComponent's props or what's passed as an argument. The latter is
useful for calling resetForm within componentWillReceiveProps.
setErrors: (fields: { [field: string]: string }) => voidSet errors imperatively.
setFieldError: (field: string, errorMsg: string) => voidSet the error message of a field imperatively. field should match the key of
errors you wish to update. Useful for creating custom input error handlers.
setFieldTouched: (field: string, isTouched: boolean, shouldValidate?: boolean) => voidSet the touched state of a field imperatively. field should match the key of
touched you wish to update. Useful for creating custom input blur handlers. Calling this method 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 third argument as false.
setFieldValue: (field: string, value: any, shouldValidate?: boolean) => voidSet the value of a field imperatively. field should match the key of
values you wish to update. Useful for creating custom input change handlers. 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 third argument as false.
setStatus: (status?: any) => voidSet a top-level status to anything you want imperatively. Useful for
controlling arbitrary top-level state related to your form. For example, you can
use it to pass API responses back into your component in handleSubmit.
setSubmitting: (isSubmitting: boolean) => voidSet isSubmitting imperatively.
setTouched: (fields: { [field: string]: boolean }) => voidSet touched imperatively.
setValues: (fields: { [field: string]: any }) => voidSet values imperatively.
status?: anyA top-level status object that you can use to represent form state that can't otherwise be expressed/stored with other methods. This is useful for capturing and passing through API responses to your inner component.
status should only be modifed by calling
setStatus: (status?: any) => void
touched: { [field: string]: boolean }Touched fields. Each key corresponds to a field that has been touched/visited.
values: { [field: string]: any }Your form's values. Will have the shape of the result of mapPropsToValues
(if specified) or all props that are not functions passed to your wrapped
component.
validateForm: (values?: any) => voidImperatively call your validate or [validateSchema] depending on what was specified. You can optionally pass values to validate against and this modify Formik state accordingly, otherwise this will use the current values of the form.
component<Formik component={ContactForm} />;
const ContactForm = ({
handleSubmit,
handleChange,
handleBlur,
values,
errors,
}) => (
<form onSubmit={handleSubmit}>
<input
type="text"
onChange={handleChange}
onBlur={handleBlur}
value={values.name}
name="name"
/>
{errors.name && <div>{errors.name}</div>}
<button type="submit">Submit</button>
</form>
};
Warning: <Formik component> takes precendence over <Formik render> so
don’t use both in the same <Formik>.
render: (props: FormikProps<Values>) => ReactNode<Formik render={props => <ContactForm {...props} />}/>
<Formik
render={({ handleSubmit, handleChange, handleBlur, values, errors }) => (
<form onSubmit={handleSubmit}>
<input
type="text"
onChange={handleChange}
onBlur={handleBlur}
value={values.name}
name="name"
/>
{errors.name &&
<div>
{errors.name}
</div>}
<button type="submit">Submit</button>
</form>
)}
/>
children: func<Formik children={props => <ContactForm {...props} />}/>
// or...
<Formik>
{({ handleSubmit, handleChange, handleBlur, values, errors }) => (
<form onSubmit={handleSubmit}>
<input
type="text"
onChange={handleChange}
onBlur={handleBlur}
value={values.name}
name="name"
/>
{errors.name &&
<div>
{errors.name}
</div>}
<button type="submit">Submit</button>
</form>
)}
</Formik>
enableReinitialize?: booleanDefault is false. Control whether Formik should reset the form if
[initialValues] changes (using deep equality).
isInitialValid?: booleanDefault is false. Control the initial value of isValid prop prior to
mount. You can also pass a function. Useful for situations when you want to
enable/disable a submit and reset buttons on initial mount.
initialValues?: ValuesInitial field values of the form, Formik will make these values available to
render methods component as props.values.
Even if your form is empty by default, you must initialize all fields with initial values otherwise React will throw an error saying that you have changed an input from uncontrolled to controlled.
Note: initialValues not available to the higher-order component, use
mapPropsToValues instead.
onReset?: (values: Values, formikBag: FormikBag) => voidYour optional form reset handler. It is passed your forms values and the
"FormikBag".
onSubmit: (values: Values, formikBag: FormikBag) => voidYour form submission handler. It is passed your forms values and the
"FormikBag", which includes an object containing a subset of the
injected props and methods (i.e. all the methods
with names that start with set<Thing> + resetForm) and any props that were
passed to the the wrapped component.
Note: errors, touched, status and all event handlers are NOT
included in the FormikBag.
validate?: (values: Values) => FormikError<Values> | Promise<any>Note: I suggest using validationSchema and Yup for validation. However,
validate is a dependency-free, straightforward way to validate your forms.
Validate the form's values with function. This function can either be:
errors object.// Synchronous validation
const validate = (values, props) => {
let errors = {};
if (!values.email) {
errors.email = 'Required';
} else if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(values.email)) {
errors.email = 'Invalid email address';
}
//...
return errors;
};
errors object// Async Validation
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
const validate = (values, props) => {
return sleep(2000).then(() => {
let errors = {}
if (['admin', 'null', 'god']).includes(values.username) {
errors.username = 'Nice try'
}
// ...
if (Object.keys(errors).length) {
throw errors
}
})
}
validateOnBlur?: booleanDefault is true. Use this option to run validations on blur events. More
specifically, when either handleBlur, setFieldTouched, or setTouched
are called.
validateOnChange?: booleanDefault is true. Use this option to tell Formik to run validations on change
events and change-related methods. More specifically, when either
handleChange, setFieldValue, or setValues are called.
validationSchema?: Schema | (() => Schema)A Yup schema or a function that returns a Yup
schema. This is used for validation. Errors are mapped by key to the inner
component's errors. Its keys should match those of values.
<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
<input/> element. To change the underlying element of <Field/>, specify a
component prop. It can either be a string like select or another React
component. <Field/> can also take a render prop.
import React from 'react';
import { Formik, Field } from 'formik';
const Example = () => (
<div>
<h1>My Form</h1>
<Formik
initialValues={{ email: '', color: 'red', firstName: '' }}
onSubmit={(values, actions) => {
setTimeout(() => {
alert(JSON.stringify(values, null, 2));
actions.setSubmitting(false);
}, 1000);
}}
render={(props: FormikProps<Values>) => (
<form onSubmit={props.handleSubmit}>
<Field type="email" name="email" placeholder="Email" />
<Field component="select" name="color">
<option value="red">Red</option>
<option value="green">Green</option>
<option value="blue">Blue</option>
</Field>
<Field name="firstName" component={CustomInputComponent} />
<Field
name="lastName"
render={({ field /* _form */ }) => (
<input {...field} placeholder="firstName" />
)}
/>
<button type="submit">Submit</button>
</form>
)}
/>
</div>
);
const CustomInputComponent: React.SFC<
FieldProps<Values> & CustomInputProps
> = ({
field, // { name, value, onChange, onBlur }
form: { touched, errors }, // also values, setXXXX, handleXXXX, dirty, isValid, status, etc.
...props
}) => (
<div>
<input type="text" {...field} {...props} />
{touched[field.name] &&
errors[field.name] && <div className="error">{errors[field.name]}</div>}
</div>
);
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 be either be:
string containing the error message or
return undefined.// Synchronous validation for Field
const validate = values => {
let errorMessage;
if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(values.email)) {
errorMessage = 'Invalid email address';
}
return errorMessage;
};
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.
Asynchronous and return a Promise that's error is an string with the error message
// Async validation for Field
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
const validate = value => {
return sleep(2000).then(() => {
if (['admin', 'null', 'god'].includes(value)) {
throw 'Nice try';
}
});
};
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')).
<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.
import React from 'react';
import { Formik, Form, Field, FieldArray } from 'formik'
// Here is an example of a form with an editable list.
// Next to each input are buttons for insert and remove.
// If the list is empty, there is a button to add an item.
export const FriendList = () => (
<div>
<h1>Friend List</h1>
<Formik
initialValues={{ friends: ['jared', 'ian', 'brent'] }}
onSubmit={values =>
setTimeout(() => {
alert(JSON.stringify(values, null, 2));
}, 500)
}
render={formikProps => (
<FieldArray
name="friends"
render={arrayHelpers => (
<Form>
{values.friends && values.friends.length > 0 ? (
values.friends.map((friend, index) => (
<div>
<Field name={`friends.${index}`} />
<button
type="button"
onClick={() => arrayHelpers.remove(index) // remove a friend from the list}
>
-
</button>
<button
type="button"
onClick={() => arrayHelpers.insert(index, '') // insert an empty string at a position}
>
+
</button>
</div>
))
) : (
<button
type="button"
onClick={() => arrayHelpers.push('')}
>
{/** show this when user has removed all friends from the list */}
Add a friend
</button>
)}
<div>
<button type="submit">Submit</button>
</div>
</Form>
)}
/>
)}
/>
</div>
);
name: stringThe name or path to the relevant key in values.
validateOnChange?: booleanDefault is true. Determines if form validation should or should not be run after any array manipulations.
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,
const schema = Yup.object().shape({
friends: Yup.array()
.of(
Yup.object().shape({
name: Yup.string()
.min(4, 'too short')
.required('Required'), // these constraints take precedence
salary: Yup.string()
.min(3, 'cmon')
.required('Required'), // these constraints take precedence
})
)
.required('Must have friends') // these constraints are shown if and only if inner constraints are satisfied
.min(3, 'Minimum of 3 friends'),
});
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 contstraints)...
Bad
// within a `FieldArray`'s render
const FriendArrayErrors = errors =>
errors.friends ? <div>{errors.friends}</div> : null; // app will crash
Good
// within a `FieldArray`'s render
const FriendArrayErrors = errors =>
typeof 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:
import { Field, getIn } from 'formik';
const ErrorMessage = ({ name }) => (
<Field
name={name}
render={({ form }) => {
const error = getIn(form.errors, name);
const touch = getIn(form.touched, name);
return touch && error ? error : null;
}}
/>
);
// Usage
<ErrorMessage name="friends[0].name" />; // => null, 'too short', or 'required'
NOTE: In Formik v0.12 / 1.0, a new meta prop may be 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.
The following methods are made available via render props.
push: (obj: any) => void: Add a value to the end of an arrayswap: (indexA: number, indexB: number) => void: Swap two values in an arraymove: (from: number, to: number) => void: Move an element in an array to another indexinsert: (index: number, value: any) => void: Insert an element at a given index into the arrayunshift: (value: any) => number: Add an element to the beginning of an array and return its lengthremove<T>(index: number): T | undefined: Remove an element at an index of an array and return itpop<T>(): T | undefined: Remove and return value from the end of the arrayThere are three ways to render things with <FieldArray/>
<FieldArray name="..." component><FieldArray name="..." render>render: (arrayHelpers: ArrayHelpers) => React.ReactNodeimport React from 'react';
import { Formik, Form, Field, FieldArray } from 'formik'
export const FriendList = () => (
<div>
<h1>Friend List</h1>
<Formik
initialValues={{ friends: ['jared', 'ian', 'brent'] }}
onSubmit={...}
render={formikProps => (
<FieldArray
name="friends"
render={({ move, swap, push, insert, unshift, pop }) => (
<Form>
{/*... use these however you want */}
</Form>
)}
/>
/>
</div>
);
component: React.ReactNodeimport React from 'react';
import { Formik, Form, Field, FieldArray } from 'formik'
export const FriendList = () => (
<div>
<h1>Friend List</h1>
<Formik
initialValues={{ friends: ['jared', 'ian', 'brent'] }}
onSubmit={...}
render={formikProps => (
<FieldArray
name="friends"
component={MyDynamicForm}
/>
/>
</div>
);
// In addition to the array helpers, Formik state and helpers
// (values, touched, setXXX, etc) are provided through a `form`
// prop
export const MyDynamicForm = ({
move, swap, push, insert, unshift, pop, form
}) => (
<Form>
{/** whatever you need to do */}
</Form>
);
<Form />Like <Field/>, <Form/> is a helper component you can use to save time. It is
tiny wrapper around <form onSubmit={context.formik.handleSubmit} />. This
means you don't need to explictly type out <form onSubmit={props.handleSubmit}/> if you don't want to.
ReactDOM only
import React from 'react';
import { Formik, Field, Form } from 'formik';
const Example = () => (
<div>
<h1>My Form</h1>
<Formik
initialValues={{ email: '', color: 'red' }}
onSubmit={(values, actions) => {
setTimeout(() => {
alert(JSON.stringify(values, null, 2));
actions.setSubmitting(false);
}, 1000);
}}
component={MyForm}
/>
</div>
);
const MyForm = () => (
<Form>
<Field type="email" name="email" placeholder="Email" />
<Field component="select" name="color">
<option value="red">Red</option>
<option value="green">Green</option>
<option value="blue">Blue</option>
</Field>
<button type="submit">Submit</button>
</Form>
);
withFormik(options)Create a higher-order React component class that passes props and form handlers
(the "FormikBag") into your component derived from supplied options.
optionsdisplayName?: stringWhen your inner form component is a stateless functional component, you can use
the displayName option to give the component a proper name so you can more
easily find it in
React DevTools.
If specified, your wrapped form will show up as Formik(displayName). If
omitted, it will show up as Formik(Component). This option is not required for
class components (e.g. class XXXXX extends React.Component {..}).
enableReinitialize?: booleanDefault is false. Control whether Formik should reset the form if the wrapped
component props change (using deep equality).
handleSubmit: (values: Values, formikBag: FormikBag) => voidYour form submission handler. It is passed your forms values and the
"FormikBag", which includes an object containing a subset of the
injected props and methods (i.e. all the methods
with names that start with set<Thing> + resetForm) and any props that were
passed to the the wrapped component.
props (props passed to the wrapped component)resetFormsetErrorssetFieldErrorsetFieldTouchedsetFieldValuesetStatussetSubmittingsetTouchedsetValuesNote: errors, touched, status and all event handlers are NOT
included in the FormikBag.
isInitialValid?: boolean | (props: Props) => booleanDefault is false. Control the initial value of isValid prop prior to
mount. You can also pass a function. Useful for situations when you want to
enable/disable a submit and reset buttons on initial mount.
mapPropsToValues?: (props: Props) => ValuesIf this option is specified, then Formik will transfer its results into
updatable form state and make these values available to the new component as
props.values. If mapPropsToValues is not specified, then Formik
will map all props that are not functions to the inner component's
props.values. That is, if you omit it, Formik will only pass
props where typeof props[k] !== 'function', where k is some key.
Even if your form is not receiving any props from its parent, use
mapPropsToValues to initialize your forms empty state.
validate?: (values: Values, props: Props) => FormikError<Values> | Promise<any>Note: I suggest using validationSchema and Yup for validation. However,
validate is a dependency-free, straightforward way to validate your forms.
Validate the form's values with function. This function can either be:
errors object.// Synchronous validation
const validate = (values, props) => {
let errors = {};
if (!values.email) {
errors.email = 'Required';
} else if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(values.email)) {
errors.email = 'Invalid email address';
}
//...
return errors;
};
errors object// Async Validation
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
const validate = (values, props) => {
return sleep(2000).then(() => {
let errors = {};
if (['admin', 'null', 'god'].includes(values.username)) {
errors.username = 'Nice try';
}
// ...
if (Object.keys(errors).length) {
throw errors;
}
});
};
validateOnBlur?: booleanDefault is true. Use this option to run validations on blur events. More
specifically, when either handleBlur, setFieldTouched, or setTouched
are called.
validateOnChange?: booleanDefault is true. Use this option to tell Formik to run validations on change
events and change-related methods. More specifically, when either
handleChange, setFieldValue, or setValues are called.
validationSchema?: Schema | ((props: Props) => Schema)A Yup schema or a function that returns a Yup
schema. This is used for validation. Errors are mapped by key to the inner
component's errors. Its keys should match those of values.
These are identical to the props of <Formik render={props => ...} />
List of organizations and projects using Formik
Formik is made with <3 thanks to these wonderful people (emoji key):
 Jared Palmer 💬 💻 🎨 📖 💡 🤔 👀 ⚠️ |  Ian White 💬 🐛 💻 📖 🤔 👀 |  Andrej Badin 💬 🐛 📖 |  Adam Howard 💬 🐛 🤔 👀 |  Vlad Shcherbin 💬 🐛 🤔 |  Brikou CARRE 🐛 📖 |  Sam Kvale 🐛 💻 ⚠️ |
|---|---|---|---|---|---|---|
 Jon Tansey 🐛 💻 |  Tyler Martinez 🐛 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT License.
FAQs
Build forms in React, without the tears
The npm package formik receives a total of 2,083,076 weekly downloads. As such, formik popularity was classified as popular.
We found that formik demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."