Skip to content

Controller

Wrapper component for controlled inputs

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.

Props

The following table contains information about the arguments for useController.

NameTypeRequiredDescription
nameFieldPathUnique name of your input.
controlControlcontrol object is from invoking useForm. Optional when using FormProvider.
renderFunction

This is a render prop. A function that returns a React element and provides the ability to attach events and value into the component. This simplifies integrating with external controlled components with non-standard prop names. Provides onChange, onBlur, name, ref and value to the child component, and also a fieldState object which contains specific input state.

defaultValueunknown

Important: Can not apply undefined to defaultValue or defaultValues at useForm.

  • You need to either set defaultValue at the field-level or useForm's defaultValues. undefined is not a valid value.

  • If your form will invoke reset with default values, you will need to provide useForm with defaultValues.

  • Calling onChange with undefined is not valid. You should use null or the empty string as your default/cleared value instead.

rulesObject

Validation rules in the same format for register options, which includes:

required, min, max, minLength, maxLength, pattern, validate

shouldUnregisterboolean = false

Input will be unregistered after unmount and defaultValues will be removed as well.

Return

The following table contains information about properties which Controller produces.

stringReact.Ref
Object NameNameTypeDescription
fieldonChange(value: any) => void

A function which sends the input's value to the library.

  • It should be assigned to the onChange prop of the input and value should not be undefined.
  • This prop update formState and you should avoid manually invoke setValue or other API related to field update.

onBlur() => void

A function which sends the input's onBlur event to the library. It should be assigned to the input's onBlur prop.

valueunknown

The current value of the controlled component.

name

Input's name being registered.

ref

A ref used to connect hook form to the input. Assign ref to component's input ref to allow hook form to focus the error input.

fieldStateinvalidboolean

Invalid state for current input.

isTouchedboolean

Touched state for current controlled input.

isDirtyboolean

Dirty state for current controlled input.

errorobject

error for this specific input.

formStateisDirtyboolean

Set to true after the user modifies any of the inputs.

  • Make sure to provide all inputs' defaultValues at the useForm, so hook form can have a single source of truth to compare whether the form is dirty.

  • File typed input will need to be managed at the app level due to the ability to cancel file selection and FileList object.

dirtyFieldsobject

An object with the user-modified fields. Make sure to provide all inputs' defaultValues via useForm, so the library can compare against the defaultValues.

Dirty fields will not represent as isDirty formState, because dirty fields are marked field dirty at field level rather the entire form. If you want to determine the entire form state use isDirty instead.

touchedFieldsobjectAn object containing all the inputs the user has interacted with.
isSubmittedbooleanSet to true after the form is submitted. Will remain true until the reset method is invoked.
isSubmitSuccessfulboolean

Indicate the form was successfully submitted without any Promise rejection or Error been thrown within the handleSubmit callback.

isSubmittingbooleantrue if the form is currently being submitted. false otherwise.
submitCountnumberNumber of times the form was submitted.
isValidboolean
Set to true if the form doesn't have any errors.

Note: isValid is affected by mode at useForm. This state is only applicable with onChange, onTouched, and onBlur mode.

isValidatingbooleanSet to true during validation.
errorsobjectAn object with field errors. There is also an ErrorMessage component to retrieve error message easily.

Examples

Expo

Video

The following video showcase what's inside Controller and how its been build.

Tips

  • Do not register input again. This component is made to take care of the registration process.

  • Customise what value gets sent to hook form by transforming the value during onChange.

Thank you for your support

If you find React Hook Form to be useful in your project, please consider to star and support it.

Edit