Skip to content

useController

React hooks for controlled component

useController:
(props?: UseControllerProps) => { field: object, fieldState: object, formState: object }

This custom hook powers Controller. Additionally, it shares the same props and methods as Controller. It's useful for creating reusable Controlled input.

Props

The following table contains information about the arguments for useController.

NameTypeRequiredDescription
namestringUnique name of your input.
controlObjectcontrol object provided by invoking useForm. Optional when using FormProvider.
defaultValueanyThe same as an uncontrolled component's defaultValue. When passing a boolean value, it will be treated as checkbox input. For more details, see useForm's defaultValues section.
  • You need to either set defaultValue at the field-level or call useForm with defaultValues.

  • If your form will invoke reset with default values, you will need to call useForm with defaultValues instead of setting the defaultValue on individual fields.

rulesObject

Validation rules in the same format as for register.

Important: doesn't supportvalueAs for Controller.

rules={{ required: true }}

Return

The following table contains information about properties which useController produces.

React.RefObject
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.

onBlur(value: any) => void

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

valueunknown

The current value of the controlled component.

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.

formStateisSubmitSuccessfulboolean

Indicates whether the form was successfully submitted.

isDirtyboolean

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

isSubmittedboolean

Set to true after the form is submitted. Will remain true until the reset method is invoked.

dirtyFieldsobject

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

touchedFieldsobject

An object containing all the inputs the user has interacted with.

isSubmittingboolean

true if the form is currently being submitted. false if otherwise.

submitCountnumber

Number of times the form was submitted.

isValidboolean

Set to true if the form doesn't have any errors.

isValidatingboolean

Set to true during validation.

import React from "react";
import { TextField } from "@material-ui/core";
import { useController, useForm } from "react-hook-form";

function Input({ control, name }) {
  const {
    field: { ref, ...inputProps },
    fieldState: { invalid, isTouched, isDirty },
    formState: { touchedFields, dirtyFields }
  } = useController({
    name,
    control,
    rules: { required: true },
    defaultValue: "",
  });

  return <TextField {...inputProps} inputRef={ref} />;
}

function App() {
  const { control } = useForm();
  
  return <Input name="firstName" control={control} />;
}
import * as React from "react";
import { useForm, useController } from "./src";

function Input(props) {
  const { field, fieldState } = useController(props);

  return (
    <div>
      <input {...field} placeholder={props.name} />
      <p>{fieldState.isTouched && "Touched"}</p>
      <p>{fieldState.isDirty && "Dirty"}</p>
      <p>{fieldState.invalid ? "invalid" : "valid"}</p>
    </div>
  );
}

export default function App() {
  const { handleSubmit, control } = useForm({
    defaultValues: {
      FirstName: ""
    },
    mode: "onChange"
  });
  const onSubmit = (data) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Input control={control} name="FirstName" rules={{ required: true }} />
      <input type="submit" />
    </form>
  );
}

Tips

  • Do not register input again. This custom hook is designed to take care of the registration process.

    const { field } = useController({ name: 'test' })
    
    <input {...field} /> // ✅ 
    <input {...field} {...register('test')} /> // ❌ double up the registration        
    
  • It's ideal to use a single useController per component. If you need to use more than one, make sure you rename the prop. May want to consider using Controller instead.

    const { field: input } = useController({ name: 'test' })
    const { field: checkbox } = useController({ name: 'test1' })
    
    <input {...input} />
    <input {...checkbox} />        
    
Edit