validationSchema: Object

validationResolver: Function

This callback function allows you to run through any schema or custom validation. The function has the entire form values as argument, and you will need to validate the result and return both values and errors. Read more at section.

Note: This function will be cached inside the hook, you will have to either move the function outside of the component or memorise the function.

validationContext: Object

This context object will be injected into validationResolver's second argument or Yup validation's context object.

validateCriteriaMode: firstError | all

When set to firstError (default), only first error from each field will be gathered.

Custom Register

You can also register inputs manually, which is useful when working with custom components and Ref is not accessible. This is actually the case when you are working with React Native or custom component like react-select.

By using a custom register call, you will need to update the input value with , because input is no longer registered with its ref.

register({ name: 'firstName' }, { required: true, min: 8 })

Note: If you want the custom registered input to trigger a re-render during its value update, then you should give a type to your registered input.

errors: Record<string, Object>

Object containing form errors and error messages corresponding to each input.

Note: Difference between V3 and V4:

V4: Nested objects

Reason: optional chaining is getting widely adopted and allows better support for types..

errors?.yourDetail?.firstName;

V3: Flatten object

Reason: simple and easy to access error.

errors['yourDetail.firstName'];

Name

Type

Description

type

string

Error Type. eg: required, min, max, minLength

types

Record<{ string, string | boolean }>

This is useful when you want to return all validation errors for a single input. For instance, a password field that is required to have a minimum length AND contain a special character. Note that you need to set validateCriteriaMode to'all' for this option to work properly.

message

string

If you registered your input with an error message, then it will be put in this field. Otherwise it's an empty string by default.

This function will reset the fields' values and errors within the form. By supply omitResetState, you have the freedom to only reset specific piece of state. You can pass values as an optional argument to reset your form into assigned default values.

Note: For controlled components like React-Select which don't expose ref, you will have to reset the input value manually through or using to wrap around your controlled component.

Note: You will need to supply defaultValues at useForm to resetController components' value.

setValue:

This function allows you to dynamically set registered input/select value. At the same time, it tries to avoid re-rendering when it's not necessary. Only the following conditions will trigger a re-render:

When an error is triggered by a value update

When an error is corrected by a value update

When setValue is invoked for the first time and formState dirty is set to true

When setValue is invoked and formState touched is updated

Note: By invoking this method, formState will set the input to touched.

You can also set the shouldValidate parameter to true in order to trigger a field validation. eg: setValue('name', 'value', true)

formState: Object

This object contain information about the form state.

Important:formState is wrapped with Proxy to improve render performance, so make sure you invoke or read it before render in order to enable the state update. This reduces re-render feature only applies to the Web platform due to a lack of support on Proxy at React Native.

Name

Type

Description

dirty

boolean

Set to true after a user interacted with any of the inputs.

dirtyFields

Set

A unique set of user modified fields.

isSubmitted

boolean

Set true after a user submitted the form. After a form's submission, its' state will remain submitted until invoked with reset method.

Controller: Component

React Hook Form embraces uncontrolled components and native inputs, however it's hard to avoid working with external controlled component such as React-Select, AntD and Material-UI. This wrapper component will make it easier for you to work with them.

Every prop you pass to the Controller component will be forwarded to the component instance you provided with the as prop. For instance, if you have a custom Switch component that requires a label prop, you can pass it to the Controller component directly and it will take care of forwarding the prop for you. The name prop will be used mainly to access the value through the form later.

control object is from invoking useForm. it's optional if you are using FormContext.

defaultValue

any

The same as uncontrolled component's defaultValue, when supply boolean value, it will be treated as checkbox input.

Note: you will need to supply either defaultValue or defaultValues at useForm

Note: if your form will invoke reset with default values, you will need to provide defaultValues at useForm level instead of set inline defaultValue.

rules

Object

Validation rules in the same format as for . This object will be cached inside Controller.

onChange

(args: any | EventTarget) => any

This prop allows you to customize the return value, make sure you aware the shape of the external component value props. value or checked attribute will be read when payload's shape is an object which contains type attribute.

A custom hook for working with uncontrolled Field Arrays (dynamic inputs). The motivation behind this hook is to provide better user experience and form performance. You can watch this short video to compare controlled vs uncontrolled Field Array.

This function allow you to run any external validation methods, such as Joi, Superstruct and etc. In fact, the goal is not only limited Yup as our external (schema) validation library. We would like to support many other validation libraries to work with React Hook Form. You can even write your custom validation logic to validate.

Note: make sure you are returning object which contains values and errors, and their default value should be {}.