</> 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.

Return

The following table contains information about properties which useController produces.

Examples

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

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

  return (
    <TextField
      onChange={field.onChange} // send value to hook form
      onBlur={field.onBlur} // notify when input is touched/blur
      value={field.value} // input value
      name={field.name} // send down the input name
      inputRef={field.ref} // send input ref, so we can focus on input when error appear
    />
  )
}

import * as React from "react"
import { useForm, useController, UseControllerProps } from "react-hook-form"

type FormValues = {
  FirstName: string
}

function Input(props: UseControllerProps<FormValues>) {
  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<FormValues>({
    defaultValues: {
      FirstName: "",
    },
    mode: "onChange",
  })
  const onSubmit = (data: FormValues) => console.log(data)

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

import * as React from "react"
import { useController, useForm } from "react-hook-form"

const Checkboxes = ({ options, control, name }) => {
  const { field } = useController({
    control,
    name,
  })
  const [value, setValue] = React.useState(field.value || [])

  return (
    <>
      {options.map((option, index) => (
        <input
          onChange={(e) => {
            const valueCopy = [...value]

            // update checkbox value
            valueCopy[index] = e.target.checked ? e.target.value : null

            // send data to react hook form
            field.onChange(valueCopy)

            // update local state
            setValue(valueCopy)
          }}
          key={option}
          checked={value.includes(option)}
          type="checkbox"
          value={option}
        />
      ))}
    </>
  )
}

export default function App() {
  const { register, handleSubmit, control } = useForm({
    defaultValues: {
      controlled: [],
      uncontrolled: [],
    },
  })
  const onSubmit = (data) => console.log(data)

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <section>
        <h2>uncontrolled</h2>
        <input {...register("uncontrolled")} type="checkbox" value="A" />
        <input {...register("uncontrolled")} type="checkbox" value="B" />
        <input {...register("uncontrolled")} type="checkbox" value="C" />
      </section>

      <section>
        <h2>controlled</h2>
        <Checkboxes
          options={["a", "b", "c"]}
          control={control}
          name="controlled"
        />
      </section>
      <input type="submit" />
    </form>
  )
}

Tips

• It's important to be aware of each prop's responsibility when working with external controlled components, such as MUI, AntD, Chakra UI. Its job is to spy on the input, report, and set its value.

  • onChange: send data back to hook form
  • onBlur: report that the input has been interacted with (focus and blur)
  • value: set up input initial and updated value
  • ref: allow input to be focused with error
  • name: give input an unique name

  It's fine to host your state and combined with useController.

  CodeSandbox ^JS

  const { field } = useController();
  const [value, setValue] = useState(field.value);
  
  onChange={(event) => {
    field.onChange(parseInt(event.target.value)) // data send back to hook form
    setValue(event.target.value) // UI state
  }}

• 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} />