useController

</> useController: (UseControllerProps) => UseControllerReturn

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 "@mui/material"
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 the value to hook form
      onBlur={field.onBlur} // notify when the input is touched or blurred
      value={field.value} // input value
      name={field.name} // send the input name
      inputRef={field.ref} // send input ref, so we can focus on the input when an error appears
    />
  )
}

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 { useState } from "react"
import { useController, useForm } from "react-hook-form"

const Checkboxes = ({ options, control, name }) => {
  const { field } = useController({
    control,
    name,
  })
  const [value, setValue] = 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 — this only works if the target component forwards refs (React.forwardRef) or exposes an equivalent, like MUI's inputRef. If it doesn't accept a ref at all, omit ref from what you spread and handle focus manually.
  • name: give input an unique name

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

  CodeSandbox ^JS

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

• Do not register the 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 best to use a single useController call per component — each call creates its own subscription, so multiple calls in one component can cause extra re-renders. If you need more than one controlled field in the same component, rename the destructured field for each call to avoid naming collisions, or consider using Controller instead.

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