useWatch function definition

[vershart]

Hi!

Should useWatch accept name as a string?
E.g. name?: string

react-hook-form/src/useWatch.ts

Line 43 in 51589c5

name?: undefined;

[vershart]

Or even more specifically:

string | string[] | undefined

As per documentation

[BrendanC23]

useWatch has several overloads defined for it. This one allows you to pass a TFieldName (a string):

react-hook-form/src/useWatch.ts

Lines 70 to 81 in 51589c5

	export function useWatch<
	TFieldValues extends FieldValues = FieldValues,
	TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
	TTransformedValues = TFieldValues,
	>(props: {
	name: TFieldName;
	defaultValue?: FieldPathValue<TFieldValues, TFieldName>;
	control?: Control<TFieldValues, any, TTransformedValues>;
	disabled?: boolean;
	exact?: boolean;
	compute?: undefined;
	}): FieldPathValue<TFieldValues, TFieldName>;

You can hover over the function definition in VSCode too see the various overloaded definitions.

 
See the TypeScript docs for more information.

[vershart]

@BrendanC23 thank you for explaining.
I have asked because in the WebStorm I have seen that the provided value (string) cannot be assigned to type undefined. That was in the dist/useWatch.d.ts type definition file and then I have seen this type definition in the actual code.

Now I understand the purpose of the overloaded definition and I see it is working correctly in VS Code. Could you explain why it is not working for the IDE?

[BrendanC23]

I'm not sure why you're experiencing different behavior with WebStorm. Can you post your code? Are you able to replicate the error in a CodeSandbox/StackBlitz project?

Can you include a screenshot of the exact error message your IDE is giving you?

[vershart]

A dummy example I have created in my JS project:

import { useForm, useWatch } from 'react-hook-form';

function Example() {
  const { control } = useForm({
    mode: 'onChange',
    defaultValues: {
      field1: '',
    },
  });

  const field1 = useWatch({ control, name: 'field1' });

  return <p>Example</p>;
}

Produces the following warning from IDE side:

And IDE navigates me to the definition of the useWatch function with the name?: undefined;
It seems that it is an issue with how IDE interprets this, because in VS Code and CodeSandbox I cannot reproduce this issue and code navigation indeed leads me to the definition where name is of type TFieldName.

https://codesandbox.io/p/sandbox/hopeful-fire-qf3lrn

Environment:

WebStorm 2025.3
Build #WS-253.28294.332, built on December 5, 2025
macOS 15.5

react-hook-form@7.71.1

[Navaneethan-P]

useWatch already accepts a string value at runtime,

but I think the intended typing is FieldPath rather than string.
In the overload, TFieldName extends FieldPath, so something like:

useWatch({
control,
name: "fieldA",
})

is supported while still preserving type safety for valid field paths.

Using name?: string would make the API less type-safe because arbitrary strings would be accepted even when they don't exist in TFieldValues.

So unless there's a specific use case requiring dynamic/untyped field names, the current FieldPath approach seems intentional.