React Hook Form 12 📋 The useController Hook — Building custom controlled inputs - KandZ

⏱️ Estimated read: 15 min | |

The useController hook is the hook form of the Controller component’s contract. It accepts the name, the control, the rules, and the defaultValue, and it returns the field and the fieldState objects. The field object carries the value, the onChange, the onBlur, the name, and the ref, and the fieldState carries the invalid, the isTouched, the isDirty, the isValidating, and the error . The difference between the hook and the component is not the behavior. It is the shape of the code: the Controller returns the field and the fieldState through a render prop, and the useController returns them through the hook’s return value.

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The hook exists for the reusable component. A design system has a TextField, a Select, a CurrencyInput, and a TagsInput that are used in dozens of forms. Wrapping each one in a Controller at every call site is the duplication, and the duplication is the place where the bugs live. The useController moves the connection into the component itself, so the form passes the control and the name and the component handles the rest. The hook is the mechanism that turns a presentational component into a form-aware component without the parent knowing about React Hook Form.

The hook is also the place where the custom controlled inputs are built. A CurrencyInput that formats the value as the user types, a TagsInput that manages an array of the strings, a PasswordStrengthInput that reads the value and displays the strength—each of these needs the form’s value and the form’s change handler, and none of them can use the register because they are not native inputs. The useController is the mechanism that provides the field and the fieldState to the custom component, and the custom component is free to render whatever it wants.

Key point: The useController hook is the same contract as the Controller component, and it is the mechanism for the reusable controlled inputs. It returns the field and the fieldState, and it accepts the name, the control, the rules, and the defaultValue. The hook must be called inside a component that is a child of the useForm owner, and the control must be passed from the useForm (or read from the FormProvider). The custom component owns the rendering; the hook owns the connection.

Why the `useController` hook exists

The duplication problem. A design system has a TextField that is used in twenty forms. Wrapping it in a Controller in every form repeats the same render function, the same field.value, the same field.onChange, and the same fieldState.error mapping. The repetition is the maintenance burden: a change to the error display has to be made in twenty places. The useController moves the mapping into the component, and the twenty forms pass only the control and the name . The single place is the mechanism that removes the duplication.

The type-safety problem. A reusable component that accepts the name: string can be given the wrong field name, and the error only appears at runtime. The useController‘s generic type ties the component to the form’s shape: the Control<T> and the FieldPath<T> make the name a checked key of the form values, and the compiler rejects the typo . The generic is the mechanism that moves the field-name check to the compile time.

The composition problem. A custom input might need to combine the form’s value with the local state. A TagsInput manages the list of the tags, and the list is the form’s value; a CurrencyInput formats the number, and the formatted string is the local state. The useController provides the field.value and the field.onChange, and the component composes them with the local state as it sees fit . The composition is the mechanism that lets the custom input do the formatting, the parsing, or the transformation without the form knowing.

The Controller‘s render problem. The Controller‘s render function is called on every render of the form, and the function is recreated on every render unless it is memoized. The useController is the hook, and the component that calls it is the memoization boundary: the component re-renders when its own props change, and the field and the fieldState are the values the hook returns . The boundary is the mechanism that keeps the re-render scope tight, and the tight scope is the reason the hook is the better choice for the components that are used in the large forms.

The context problem. The control can be passed explicitly or read from the FormProvider. The explicit prop is the mechanism that keeps the dependency visible, and the context is the mechanism that keeps the component’s API clean. The useController supports both: the control prop is optional if the component is inside the FormProvider . The choice is the project’s convention, and the hook supports both.

a. The hook’s return value and the custom input

The useController hook returns the field and the fieldState. The field is the object that the component spreads or passes to the input, and the fieldState is the object that the component reads for the error and the disabled state.

// The useController basic usage
import { useController, type Control, type FieldValues, type FieldPath } from "react-hook-form";

type CustomInputProps<T extends FieldValues> = {
  control: Control<T>;
  name: FieldPath<T>;
  label: string;
};

function CustomInput<T extends FieldValues>({ control, name, label }: CustomInputProps<T>) {
  // The hook connects the component to the form.
  const {
    field,       // The value, the onChange, the onBlur, the name, the ref
    fieldState,  // The invalid, the isTouched, the isDirty, the error
  } = useController({ control, name });

  return (
    <div>
      <label htmlFor={name}>{label}</label>
      {/* The field.value is the controlled value. */}
      {/* The field.onChange is the change handler. */}
      <input
        id={name}
        value={field.value ?? ""}
        onChange={field.onChange}
        onBlur={field.onBlur}
        name={field.name}
        ref={field.ref}
        aria-invalid={fieldState.invalid}
      />
      {/* The fieldState.error.message is the field-level error. */}
      {fieldState.error && <p role="alert">{fieldState.error.message}</p>}
    </div>
  );
}

The field.value ?? "" is the mechanism that prevents the uncontrolled warning: if the value is undefined, the empty string is the fallback, and the input starts controlled . The aria-invalid and the role="alert" are the accessibility mechanisms, and the fieldState.error is the data they read.

The field.ref is the mechanism that the form uses to focus the field when the validation fails. The ref is passed to the native input, and the form’s setFocus call is the mechanism that moves the focus to the field .

// The setFocus on error
const { setFocus } = useForm();

// The form can focus the field with the error.
setFocus("email");

The field.ref and the setFocus are the mechanism that connects the form’s focus management to the custom input, and the connection is the reason the custom input is as usable as the native one.

b. The custom inputs with the transformation and the composition

A CurrencyInput formats the number as the user types, and the formatted value is the local state. The useController provides the numeric value, and the component handles the formatting.

// The CurrencyInput
import { useController, type Control } from "react-hook-form";
import { useState } from "react";

type CurrencyInputProps = {
  control: Control<{ amount: number }>;
  name: "amount";
};

function CurrencyInput({ control, name }: CurrencyInputProps) {
  const { field, fieldState } = useController({ control, name });

  // The local state holds the formatted string.
  const [display, setDisplay] = useState(() =>
    field.value ? field.value.toFixed(2) : ""
  );

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    // The raw value is the input's string.
    const raw = event.target.value.replace(/[^0-9.]/g, "");
    // The local state is the formatted string.
    setDisplay(raw);
    // The form value is the parsed number.
    const parsed = parseFloat(raw);
    field.onChange(isNaN(parsed) ? undefined : parsed);
  };

  return (
    <div>
      <label htmlFor={name}>Amount</label>
      <input
        id={name}
        value={display}
        onChange={handleChange}
        onBlur={field.onBlur}
        ref={field.ref}
        aria-invalid={fieldState.invalid}
      />
      {fieldState.error && <p role="alert">{fieldState.error.message}</p>}
    </div>
  );
}

The field.onChange(isNaN(parsed) ? undefined : parsed) is the mechanism that passes the parsed number to the form and the undefined for the empty input. The undefined is the valid value for the empty numeric field, and the schema or the rule is the mechanism that decides whether it is acceptable . The local display is the formatted string, and the form value is the number. The two are the mechanism that separates the presentation from the data.

A TagsInput manages the array of the strings. The useController provides the array value, and the component adds and removes the tags.

// The TagsInput
function TagsInput({ control, name }: { control: Control<{ tags: string[] }>; name: "tags" }) {
  const { field, fieldState } = useController({ control, name });
  const [input, setInput] = useState("");

  const addTag = () => {
    if (input.trim() && !field.value.includes(input.trim())) {
      // The field.onChange receives the new array.
      field.onChange([...field.value, input.trim()]);
      setInput("");
    }
  };

  const removeTag = (tag: string) => {
    // The new array is the filtered array.
    field.onChange(field.value.filter((t) => t !== tag));
  };

  return (
    <div>
      <ul>
        {field.value.map((tag) => (
          <li key={tag}>
            {tag}
            <button type="button" onClick={() => removeTag(tag)}>Remove</button>
          </li>
        ))}
      </ul>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => e.key === "Enter" && addTag()}
      />
      {fieldState.error && <p role="alert">{fieldState.error.message}</p>}
    </div>
  );
}

The field.onChange([...field.value, input.trim()]) is the mechanism that appends the tag. The array is the new reference, and the new reference is the mechanism that the isDirty comparison uses. The field.value.filter is the mechanism that removes the tag, and the filtered array is the new reference.

The Controller‘s render prop is the alternative to the useController for the one-off custom inputs. The hook is the choice for the reusable components, and the component is the choice for the inline custom input that is used once.

Complete Example Session

// ============================================
// PART 1: THE BASIC USE CONTROLLER
// ============================================

import { useController, type Control } from "react-hook-form";

function CustomInput({ control, name }: { control: Control<FormValues>; name: "email" }) {
  const { field, fieldState } = useController({ control, name });

  return (
    <input
      value={field.value ?? ""}
      onChange={field.onChange}
      onBlur={field.onBlur}
      ref={field.ref}
      aria-invalid={fieldState.invalid}
    />
  );
}

// ============================================
// PART 2: THE FORM THAT USES THE CUSTOM INPUT
// ============================================

function LoginForm() {
  const { control, handleSubmit } = useForm<FormValues>({
    defaultValues: { email: "" },
  });

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <CustomInput control={control} name="email" />
      <button type="submit">Log in</button>
    </form>
  );
}

// ============================================
// PART 3: THE TYPE-SAFE NAME
// ============================================

// The name is the FieldPath<FormValues>.
// The wrong name is a compile error.
<CustomInput control={control} name="invalid" /> // the TypeScript error

// ============================================
// PART 4: THE FIELD STATE
// ============================================

const { field, fieldState } = useController({ control, name });

// The fieldState.invalid is the field-level invalid state.
// The fieldState.error is the field-level error.
// The fieldState.isTouched is the blur state.

// ============================================
// PART 5: THE VALIDATION RULES
// ============================================

const { field } = useController({
  control,
  name: "email",
  rules: {
    required: "The email is required.",
    pattern: { value: /^\S+@\S+$/i, message: "The email is invalid." },
  },
});

// The rules are the same as the register options.

// ============================================
// PART 6: THE CURRENCY INPUT
// ============================================

function CurrencyInput({ control }: { control: Control<{ amount: number }> }) {
  const { field, fieldState } = useController({ control, name: "amount" });
  const [display, setDisplay] = useState(field.value?.toFixed(2) ?? "");

  return (
    <input
      value={display}
      onChange={(e) => {
        setDisplay(e.target.value);
        const parsed = parseFloat(e.target.value);
        field.onChange(isNaN(parsed) ? undefined : parsed);
      }}
      onBlur={field.onBlur}
      ref={field.ref}
    />
  );
}

// ============================================
// PART 7: THE TAGS INPUT
// ============================================

function TagsInput({ control }: { control: Control<{ tags: string[] }> }) {
  const { field } = useController({ control, name: "tags" });

  const addTag = (tag: string) => {
    field.onChange([...field.value, tag]);
  };

  return (
    <div>
      {field.value.map((tag) => (
        <span key={tag}>{tag}</span>
      ))}
    </div>
  );
}

// ============================================
// PART 8: THE SET FOCUS
// ============================================

const { setFocus } = useForm();

// The setFocus focuses the field.
setFocus("email");

// The field.ref is the mechanism that makes it work.

// ============================================
// PART 9: THE FORM PROVIDER
// ============================================

// The useController reads the control from the FormProvider.
<FormProvider {...methods}>
  <CustomInput name="email" />
</FormProvider>

// ============================================
// PART 10: THE CHECKLIST
// ============================================

// [ ] The useController is called inside the component.
// [ ] The control is passed from the useForm or the FormProvider.
// [ ] The field.value and the field.onChange are passed.
// [ ] The fieldState.error is displayed.
// [ ] The generic type ties the name to the form shape.
// [ ] The field.ref is passed to the native input.

The ten parts covered the basic useController, the form that uses the custom input, the type-safe name, the field state, the validation rules, the currency input, the tags input, the setFocus, the FormProvider, and the checklist. The through-line is that the hook is the connection, and the component is the rendering.

Quick Reference

The `useController` props

Prop	Required	Purpose
`name`	Yes	The field path
`control`	No (with the `FormProvider`)	The form control
`rules`	No	The validation rules
`defaultValue`	No	The field-level fallback
`shouldUnregister`	No	The unmount behavior

The `useController` return

Property	Purpose
`field`	The `value`, the `onChange`, the `onBlur`, the `name`, the `ref`
`fieldState`	The `invalid`, the `isTouched`, the `isDirty`, the `error`

The generic types

Type	Purpose
`Control<T>`	The control for the form `T`
`FieldPath<T>`	The valid field path for the form `T`
`FieldValues`	The generic form values constraint

The `useController` vs `Controller`

Aspect	`Controller`	`useController`
The form	The component	The hook
The reuse	The one-off	The reusable component
The render	The `render` prop	The component body

Best Practices

✅ Do This:

// Use the generic type for the reusable component
function TextInput<T extends FieldValues>({ control, name }: Props<T>) {} // ✅

// Fall back to the empty string for the undefined value
value={field.value ?? ""}                                          // ✅

// Pass the field.ref to the native input
ref={field.ref}                                                    // ✅

❌ Don’t Do This:

// Call the hook outside a component
const { field } = useController({ control, name: "email" }); // the invalid call // ❌

// Ignore the fieldState.error
<input {...field} /> // the error is not displayed                // ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The input is not connected	The `control` is not passed and no `FormProvider`	Pass the `control` or wrap in the provider
The uncontrolled warning appears	The `field.value` is `undefined`	Use the `?? ""` fallback
The error is not displayed	The `fieldState.error` is not read	Render the `fieldState.error.message`
The focus on error does not work	The `field.ref` is not passed	Pass the `ref` to the native input
The name is not type-safe	The `name` is typed as the `string`	Use the `FieldPath<T>`

Real-World Examples

1. The basic useController

const { field } = useController({ control, name: "email" });

2. The field state

const { field, fieldState } = useController({ control, name: "email" });

3. The generic type

function TextInput<T extends FieldValues>({ control, name }: Props<T>) {}

4. The value fallback

value={field.value ?? ""}

5. The onChange

onChange={field.onChange}

6. The error display

{fieldState.error && <p>{fieldState.error.message}</p>}

7. The currency input

field.onChange(parseFloat(raw))

8. The tags input

field.onChange([...field.value, tag])

9. The FormProvider

<FormProvider {...methods}><CustomInput name="email" /></FormProvider>

10. The setFocus

setFocus("email")

Visual

The Hook’s Return

┌──────────────────────────────────────────────────────────────┐
│  THE useController RETURN                                    │
│                                                              │
│  useController({ control, name })                            │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ field               │  The value, the onChange, the      │
│  │                     │  onBlur, the name, the ref         │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ fieldState          │  The invalid, the isTouched, the   │
│  │                     │  error, the isDirty                │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Reusable Component

┌──────────────────────────────────────────────────────────────┐
│  THE REUSABLE COMPONENT                                      │
│                                                              │
│  The form                                                    │
│  ┌─────────────────────┐                                    │
│  │ <TextInput          │  The control and the name          │
│  │   control={control} │                                    │
│  │   name="email" />   │                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ useController       │  The hook inside the component     │
│  │                     │  The field and the fieldState      │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Custom Input Composition

┌──────────────────────────────────────────────────────────────┐
│  THE CUSTOM INPUT                                            │
│                                                              │
│  The form value                                              │
│  ┌─────────────────────┐                                    │
│  │ field.value         │  The number                        │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The local state     │  The formatted string              │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ field.onChange      │  The parsed number                 │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
The hook	`useController({ control, name, rules, defaultValue })`
The return	The `field` and the `fieldState`
The `field`	The `value`, the `onChange`, the `onBlur`, the `name`, the `ref`
The `fieldState`	The `invalid`, the `isTouched`, the `isDirty`, the `error`
The generic	The `Control<T>` and the `FieldPath<T>`
The connection	The `control` prop or the `FormProvider`

Key takeaways:

The useController is the hook form of the Controller contract. It returns the field and the fieldState, and it accepts the name, the control, the rules, and the defaultValue . The difference is the shape: the hook returns the values, and the component receives them through the render prop.
The hook is the mechanism for the reusable components. The design-system component calls the hook internally, and the form passes the control and the name. The duplication is removed, and the single error-display mapping is the reason.
The generic type makes the name type-safe. The Control<T> and the FieldPath<T> tie the component to the form’s shape, and the wrong field name is a compile error .
The field.value ?? "" is the fallback that prevents the uncontrolled warning. The undefined value is the invalid initial state, and the empty string is the safe default .
The field.ref is the mechanism for the focus on error. The setFocus call is the mechanism that moves the focus to the field, and the ref is the connection between the form and the native input.

Remember: The React Hook Form useController is the hook that connects the custom controlled input to the form. The field object carries the value and the handlers, and the fieldState carries the error and the interaction state. The generic type makes the name type-safe, and the control is the connection. The hook is the reusable form of the Controller, and the custom input is the rendering.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!

Why the useController hook exists