Skip to content

useWatch

React Hook for subscribe to input changes

useWatch:
({ control?: Control, name?: string, defaultValue?: unknown, disabled?: boolean }) => object

Behaves similarly to the watch API, however, this will isolate re-rendering at the custom hook level and potentially result in better performance for your application.

Props

NameTypeDescription
namestring | string[] | undefinedName of the field.
controlObjectcontrol object provided by useForm. It's optional if you are using FormContext.
defaultValueunknown

default value for useWatch to return before the initial render.

Note: the first render will always return defaultValue when it's supplied.

disabledboolean = false

Option to disable the subscription.

exactboolean = false

This prop will enable an exact match for input name subscriptions.

Rules

  • The initial return value from useWatch will always return what's inside of defaultValue or defaultValues from useForm.

  • The only different between useWatch and watch is at root (useForm) level or the custom hook level update.

  • useWatch execution order matters, which means if you are update form value before the subscription is in place, then the value update will be ignored.

    setValue('test', 'data');
useWatch({ name: 'test' }); // ❌ subscription is happened after value update, no update received

useWatch({ name: 'example' }); // ✅ input value update will be received and trigger re-render
setValue('example', 'data');

  • useWatch result is optimised for render phase instead of useEffect's deps, to detect value update you may want to use an external custom hook for value comparison.

Examples

CodeSandbox 
import React from "react";
import { useForm, useWatch } from "react-hook-form";

function Child({ control }) {
  const firstName = useWatch({
    control,
    name: "firstName",
  });

  return <p>Watch: {firstName}</p>;
}

export default function App() {
  const { register, control } = useForm({
    firstName: "test"
  });
  
  return (
    <form>
      <input {...register("firstName")} />
      <Child control={control} />
    </form>
  );
}
CodeSandbox 
import React from "react";
import { useWatch } from "react-hook-form";

function totalCal(results) {
  let totalValue = 0;

  for (const key in results) {
    for (const value in results[key]) {
      if (typeof results[key][value] === "string") {
        const output = parseInt(results[key][value], 10);
        totalValue = totalValue + (Number.isNaN(output) ? 0 : output);
      } else {
        totalValue = totalValue + totalCal(results[key][value], totalValue);
      }
    }
  }

  return totalValue;
}

export const Calc = ({ control, setValue }) => {
  const results = useWatch({ control, name: "test" });
  const output = totalCal(results);

  // isolated re-render to calc the result with Field Array
  console.log(results);

  setValue("total", output);

  return <p>{output}</p>;
};

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