react-hook-form

react-hook-form

Version 7.52.1
Published 24 days ago
904 kB
No dependencies
MIT license

Install

npm i react-hook-form

yarn add react-hook-form

pnpm add react-hook-form

Overview

Performant, flexible and extensible forms library for React Hooks

Index

Functions

function appendErrors

appendErrors: (
    name: InternalFieldName,
    validateAllFieldCriteria: boolean,
    errors: InternalFieldErrors,
    type: string,
    message: ValidateResult
) => {};

function Controller

Controller: <
    TFieldValues extends FieldValues = FieldValues,
    TName extends Path<TFieldValues> = Path<TFieldValues>
>(
    props: ControllerProps<TFieldValues, TName>
) => any;

Component based on useController hook to work with controlled component.

Parameter props

the path name to the form field value, and validation rules.

Returns

provide field handler functions, field and form state.

Remarks

[API](https://react-hook-form.com/docs/usecontroller/controller) • [Demo](https://codesandbox.io/s/react-hook-form-v6-controller-ts-jwyzw) • [Video](https://www.youtube.com/watch?v=N2UNk_UCVyA)

Example 1

function App() {
  const { control } = useForm<FormValues>({
    defaultValues: {
      test: ""
    }
  });

  return (
    <form>
      <Controller
        control={control}
        name="test"
        render={({ field: { onChange, onBlur, value, ref }, formState, fieldState }) => (
          <>
            <input
              onChange={onChange} // send value to hook form
              onBlur={onBlur} // notify when input is touched
              value={value} // return updated value
              ref={ref} // set ref for focus management
            />
            <p>{formState.isSubmitted ? "submitted" : ""}</p>
            <p>{fieldState.isTouched ? "touched" : ""}</p>
          </>
        )}
      />
    </form>
  );
}

function Form

Form: <T extends FieldValues, U extends FieldValues = undefined>(
    props: FormProps<T, U>
) => React.JSX.Element;

Form component to manage submission.

Parameter props

to setup submission detail. FormProps

Returns

form component or headless render prop.

Example 1

function App() {
  const { control, formState: { errors } } = useForm();

  return (
    <Form action="/api" control={control}>
      <input {...register("name")} />
      <p>{errors?.root?.server && 'Server error'}</p>
      <button>Submit</button>
    </Form>
  );
}

function FormProvider

FormProvider: <
    TFieldValues extends FieldValues,
    TContext = any,
    TTransformedValues extends FieldValues = undefined
>(
    props: FormProviderProps<TFieldValues, TContext, TTransformedValues>
) => React.JSX.Element;

A provider component that propagates the useForm methods to all children components via [React Context](https://reactjs.org/docs/context.html) API. To be used with useFormContext.

Parameter props

all useForm methods

Remarks

[API](https://react-hook-form.com/docs/useformcontext) • [Demo](https://codesandbox.io/s/react-hook-form-v7-form-context-ytudi)

Example 1

function App() {
  const methods = useForm();
  const onSubmit = data => console.log(data);

  return (
    <FormProvider {...methods} >
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <NestedInput />
        <input type="submit" />
      </form>
    </FormProvider>
  );
}

 function NestedInput() {
  const { register } = useFormContext(); // retrieve all hook methods
  return <input {...register("test")} />;
}

function get

get: <T>(object: T, path?: string, defaultValue?: unknown) => any;

function set

set: (
    object: FieldValues,
    path: string,
    value?: unknown
) => FieldValues | undefined;

function useController

useController: <
    TFieldValues extends FieldValues = FieldValues,
    TName extends Path<TFieldValues> = Path<TFieldValues>
>(
    props: UseControllerProps<TFieldValues, TName>
) => UseControllerReturn<TFieldValues, TName>;

Custom hook to work with controlled component, this function provide you with both form and field level state. Re-render is isolated at the hook level.
Parameter props
the path name to the form field value, and validation rules.
Returns
field properties, field and form state. UseControllerReturn
Remarks
[API](https://react-hook-form.com/docs/usecontroller) • [Demo](https://codesandbox.io/s/usecontroller-0o8px)
Example 1
function Input(props) { const { field, fieldState, formState } = useController(props); return ( <div> <input {...field} placeholder={props.name} /> <p>{fieldState.isTouched && "Touched"}</p> <p>{formState.isSubmitted ? "submitted" : ""}</p> </div> ); }

function useFieldArray

useFieldArray: <
    TFieldValues extends FieldValues = FieldValues,
    TFieldArrayName extends ArrayPath<TFieldValues> = ArrayPath<TFieldValues>,
    TKeyName extends string = 'id'
>(
    props: UseFieldArrayProps<TFieldValues, TFieldArrayName, TKeyName>
) => UseFieldArrayReturn<TFieldValues, TFieldArrayName, TKeyName>;

A custom hook that exposes convenient methods to perform operations with a list of dynamic inputs that need to be appended, updated, removed etc. • [Demo](https://codesandbox.io/s/react-hook-form-usefieldarray-ssugn) • [Video](https://youtu.be/4MrbfGSFY2A)

Parameter props

useFieldArray props

Returns

methods - functions to manipulate with the Field Arrays (dynamic inputs) UseFieldArrayReturn

Remarks

[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/react-hook-form-usefieldarray-ssugn)

Example 1

function App() {
  const { register, control, handleSubmit, reset, trigger, setError } = useForm({
    defaultValues: {
      test: []
    }
  });
  const { fields, append } = useFieldArray({
    control,
    name: "test"
  });

  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      {fields.map((item, index) => (
         <input key={item.id} {...register(`test.${index}.firstName`)}  />
      ))}
      <button type="button" onClick={() => append({ firstName: "bill" })}>
        append
      </button>
      <input type="submit" />
    </form>
  );
}

function useForm

useForm: <
    TFieldValues extends FieldValues = FieldValues,
    TContext = any,
    TTransformedValues extends FieldValues = undefined
>(
    props?: UseFormProps<TFieldValues, TContext>
) => UseFormReturn<TFieldValues, TContext, TTransformedValues>;

Custom hook to manage the entire form.

Parameter props

form configuration and validation parameters.

Returns

methods - individual functions to manage the form state. UseFormReturn

Remarks

[API](https://react-hook-form.com/docs/useform) • [Demo](https://codesandbox.io/s/react-hook-form-get-started-ts-5ksmm) • [Video](https://www.youtube.com/watch?v=RkXv4AXXC_4)

Example 1

function App() {
  const { register, handleSubmit, watch, formState: { errors } } = useForm();
  const onSubmit = data => console.log(data);

  console.log(watch("example"));

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input defaultValue="test" {...register("example")} />
      <input {...register("exampleRequired", { required: true })} />
      {errors.exampleRequired && <span>This field is required</span>}
      <button>Submit</button>
    </form>
  );
}

function useFormContext

useFormContext: <
    TFieldValues extends FieldValues,
    TContext = any,
    TransformedValues extends FieldValues = undefined
>() => UseFormReturn<TFieldValues, TContext, TransformedValues>;

This custom hook allows you to access the form context. useFormContext is intended to be used in deeply nested structures, where it would become inconvenient to pass the context as a prop. To be used with FormProvider.

Returns

return all useForm methods

Remarks

[API](https://react-hook-form.com/docs/useformcontext) • [Demo](https://codesandbox.io/s/react-hook-form-v7-form-context-ytudi)

Example 1

function App() {
  const methods = useForm();
  const onSubmit = data => console.log(data);

  return (
    <FormProvider {...methods} >
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <NestedInput />
        <input type="submit" />
      </form>
    </FormProvider>
  );
}

 function NestedInput() {
  const { register } = useFormContext(); // retrieve all hook methods
  return <input {...register("test")} />;
}

function useFormState

useFormState: <TFieldValues extends FieldValues = FieldValues>(
    props?: UseFormStateProps<TFieldValues>
) => UseFormStateReturn<TFieldValues>;

This custom hook allows you to subscribe to each form state, and isolate the re-render at the custom hook level. It has its scope in terms of form state subscription, so it would not affect other useFormState and useForm. Using this hook can reduce the re-render impact on large and complex form application.

Parameter props

include options on specify fields to subscribe. UseFormStateReturn

Remarks

[API](https://react-hook-form.com/docs/useformstate) • [Demo](https://codesandbox.io/s/useformstate-75xly)

Example 1

function App() {
  const { register, handleSubmit, control } = useForm({
    defaultValues: {
    firstName: "firstName"
  }});
  const { dirtyFields } = useFormState({
    control
  });
  const onSubmit = (data) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName")} placeholder="First Name" />
      {dirtyFields.firstName && <p>Field is dirty.</p>}
      <input type="submit" />
    </form>
  );
}

function useWatch

useWatch: {
    <TFieldValues extends FieldValues = FieldValues>(props: {
        defaultValue?: DeepPartialSkipArrayKey<TFieldValues>;
        control?: Control<TFieldValues>;
        disabled?: boolean;
        exact?: boolean;
    }): DeepPartialSkipArrayKey<TFieldValues>;
    <
        TFieldValues extends FieldValues = FieldValues,
        TFieldName extends Path<TFieldValues> = Path<TFieldValues>
    >(props: {
        name: TFieldName;
        defaultValue?: PathValue<TFieldValues, TFieldName>;
        control?: Control<TFieldValues, any>;
        disabled?: boolean;
        exact?: boolean;
    }): PathValue<TFieldValues, TFieldName>;
    <
        TFieldValues extends FieldValues = FieldValues,
        TFieldNames extends readonly Path<TFieldValues>[] = readonly Path<TFieldValues>[]
    >(props: {
        name: readonly [...TFieldNames];
        defaultValue?: DeepPartialSkipArrayKey<TFieldValues>;
        control?: Control<TFieldValues, any>;
        disabled?: boolean;
        exact?: boolean;
    }): {
        [K in keyof TFieldNames]: PathValue<
            TFieldValues,
            TFieldNames[K] & Path<TFieldValues>
        >;
    };
    <
        TFieldValues extends FieldValues = FieldValues
    >(): DeepPartialSkipArrayKey<TFieldValues>;
};

Subscribe to the entire form values change and re-render at the hook level.
Parameter props
defaultValue, disable subscription and match exact name.
Remarks
[API](https://react-hook-form.com/docs/usewatch) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-usewatch-h9i5e)
Example 1
const { control } = useForm(); const values = useWatch({ control, defaultValue: { name: "data" }, exact: false, })
Custom hook to subscribe to field change and isolate re-rendering at the component level.
Parameter props
defaultValue, disable subscription and match exact name.
Remarks
[API](https://react-hook-form.com/docs/usewatch) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-usewatch-h9i5e)
Example 1
const { control } = useForm(); const values = useWatch({ control, name: "fieldA", defaultValue: "default value", exact: false, })
Custom hook to subscribe to field change and isolate re-rendering at the component level.
Parameter props
defaultValue, disable subscription and match exact name.
Remarks
[API](https://react-hook-form.com/docs/usewatch) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-usewatch-h9i5e)
Example 1
const { control } = useForm(); const values = useWatch({ control, name: ["fieldA", "fieldB"], defaultValue: { fieldA: "data", fieldB: "data" }, exact: false, })
Custom hook to subscribe to field change and isolate re-rendering at the component level.
Remarks
[API](https://react-hook-form.com/docs/usewatch) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-usewatch-h9i5e)
Example 1
// can skip passing down the control into useWatch if the form is wrapped with the FormProvider const values = useWatch()

Interfaces

interface ResolverOptions

interface ResolverOptions<TFieldValues extends FieldValues> {}

property criteriaMode

criteriaMode?: CriteriaMode;

property fields

fields: Record<InternalFieldName, Field['_f']>;

property names

names?: FieldName<TFieldValues>[];

property shouldUseNativeValidation

shouldUseNativeValidation: boolean | undefined;

Type Aliases

type ArrayPath

type ArrayPath<T> = T extends any ? ArrayPathInternal<T> : never;

Type which eagerly collects all paths through a type which point to an array type.
Example 1
Path<{foo: {bar: string[], baz: number[]}}> = 'foo.bar' | 'foo.baz'

type BatchFieldArrayUpdate

type BatchFieldArrayUpdate = <
    T extends Function,
    TFieldValues extends FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>
>(
    name: InternalFieldName,
    updatedFieldArrayValues?: Partial<FieldArray<TFieldValues, TFieldArrayName>>[],
    method?: T,
    args?: Partial<{
        argA: unknown;
        argB: unknown;
    }>,
    shouldSetValue?: boolean,
    shouldUpdateFieldsAndErrors?: boolean
) => void;

type BrowserNativeObject

type BrowserNativeObject = Date | FileList | File;

type ChangeHandler

type ChangeHandler = (event: { target: any; type?: any }) => Promise<void | boolean>;

type Control

type Control<TFieldValues extends FieldValues = FieldValues, TContext = any> = {
    _subjects: Subjects<TFieldValues>;
    _removeUnmounted: Noop;
    _names: Names;
    _state: {
        mount: boolean;
        action: boolean;
        watch: boolean;
    };
    _reset: UseFormReset<TFieldValues>;
    _options: UseFormProps<TFieldValues, TContext>;
    _getDirty: GetIsDirty;
    _resetDefaultValues: Noop;
    _formState: FormState<TFieldValues>;
    _updateValid: (shouldUpdateValid?: boolean) => void;
    _updateFormState: (formState: Partial<FormState<TFieldValues>>) => void;
    _fields: FieldRefs;
    _formValues: FieldValues;
    _proxyFormState: ReadFormState;
    _defaultValues: Partial<DefaultValues<TFieldValues>>;
    _getWatch: WatchInternal<TFieldValues>;
    _updateFieldArray: BatchFieldArrayUpdate;
    _getFieldArray: <TFieldArrayValues>(
        name: InternalFieldName
    ) => Partial<TFieldArrayValues>[];
    _setErrors: (errors: FieldErrors<TFieldValues>) => void;
    _updateDisabledField: (
        props: {
            disabled?: boolean;
            name: FieldName<any>;
            value?: unknown;
        } & (
            | {
                  field?: Field;
                  fields?: undefined;
              }
            | {
                  field?: undefined;
                  fields?: FieldRefs;
              }
        )
    ) => void;
    _executeSchema: (names: InternalFieldName[]) => Promise<{
        errors: FieldErrors;
    }>;
    register: UseFormRegister<TFieldValues>;
    handleSubmit: UseFormHandleSubmit<TFieldValues>;
    _disableForm: (disabled?: boolean) => void;
    unregister: UseFormUnregister<TFieldValues>;
    getFieldState: UseFormGetFieldState<TFieldValues>;
    setError: UseFormSetError<TFieldValues>;
};

type ControllerFieldState

type ControllerFieldState = {
    invalid: boolean;
    isTouched: boolean;
    isDirty: boolean;
    isValidating: boolean;
    error?: FieldError;
};

type ControllerProps

type ControllerProps<
    TFieldValues extends FieldValues = FieldValues,
    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
> = {
    render: ({
        field,
        fieldState,
        formState,
    }: {
        field: ControllerRenderProps<TFieldValues, TName>;
        fieldState: ControllerFieldState;
        formState: UseFormStateReturn<TFieldValues>;
    }) => React.ReactElement;
} & UseControllerProps<TFieldValues, TName>;

Render function to provide the control for the field.

Returns

all the event handler, and relevant field and form state.

Example 1

const { field, fieldState, formState } = useController();

<Controller
  render={({ field, formState, fieldState }) => ({
    <input
      onChange={field.onChange}
      onBlur={field.onBlur}
      name={field.name}
      ref={field.ref} // optional for focus management
    />
  })}
/>

type ControllerRenderProps

type ControllerRenderProps<
    TFieldValues extends FieldValues = FieldValues,
    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
> = {
    onChange: (...event: any[]) => void;
    onBlur: Noop;
    value: FieldPathValue<TFieldValues, TName>;
    disabled?: boolean;
    name: TName;
    ref: RefCallBack;
};

type CriteriaMode

type CriteriaMode = 'firstError' | 'all';

type CustomElement

type CustomElement<TFieldValues extends FieldValues> = Partial<HTMLElement> & {
    name: FieldName<TFieldValues>;
    type?: string;
    value?: any;
    disabled?: boolean;
    checked?: boolean;
    options?: HTMLOptionsCollection;
    files?: FileList | null;
    focus?: Noop;
};

type DeepMap

type DeepMap<T, TValue> = IsAny<T> extends true
    ? any
    : T extends BrowserNativeObject | NestedValue
    ? TValue
    : T extends object
    ? {
          [K in keyof T]: DeepMap<NonUndefined<T[K]>, TValue>;
      }
    : TValue;

type DeepPartial

type DeepPartial<T> = T extends BrowserNativeObject | NestedValue
    ? T
    : {
          [K in keyof T]?: ExtractObjects<T[K]> extends never
              ? T[K]
              : DeepPartial<T[K]>;
      };

type DeepPartialSkipArrayKey

type DeepPartialSkipArrayKey<T> = T extends BrowserNativeObject | NestedValue
    ? T
    : T extends ReadonlyArray<any>
    ? {
          [K in keyof T]: DeepPartialSkipArrayKey<T[K]>;
      }
    : {
          [K in keyof T]?: DeepPartialSkipArrayKey<T[K]>;
      };

type DeepRequired

type DeepRequired<T> = T extends BrowserNativeObject | Blob
    ? T
    : {
          [K in keyof T]-?: NonNullable<DeepRequired<T[K]>>;
      };

type DefaultValues

type DefaultValues<TFieldValues> =
    TFieldValues extends AsyncDefaultValues<TFieldValues>
        ? DeepPartial<Awaited<TFieldValues>>
        : DeepPartial<TFieldValues>;

type DelayCallback

type DelayCallback = (wait: number) => void;

type EmptyObject

type EmptyObject = {
    [K in string | number]: never;
};

type ErrorOption

type ErrorOption = {
    message?: Message;
    type?: LiteralUnion<keyof RegisterOptions, string>;
    types?: MultipleFieldErrors;
};

type EventType

type EventType =
    | 'focus'
    | 'blur'
    | 'change'
    | 'changeText'
    | 'valueChange'
    | 'contentSizeChange'
    | 'endEditing'
    | 'keyPress'
    | 'submitEditing'
    | 'layout'
    | 'selectionChange'
    | 'longPress'
    | 'press'
    | 'pressIn'
    | 'pressOut'
    | 'momentumScrollBegin'
    | 'momentumScrollEnd'
    | 'scroll'
    | 'scrollBeginDrag'
    | 'scrollEndDrag'
    | 'load'
    | 'error'
    | 'progress'
    | 'custom';

type ExtractObjects

type ExtractObjects<T> = T extends infer U ? (U extends object ? U : never) : never;

type Field

type Field = {
    _f: {
        ref: Ref;
        name: InternalFieldName;
        refs?: HTMLInputElement[];
        mount?: boolean;
    } & RegisterOptions;
};

type FieldArray

type FieldArray<
    TFieldValues extends FieldValues = FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>
> = FieldArrayPathValue<TFieldValues, TFieldArrayName> extends
    | ReadonlyArray<infer U>
    | null
    | undefined
    ? U
    : never;

type FieldArrayMethodProps

type FieldArrayMethodProps = {
    shouldFocus?: boolean;
    focusIndex?: number;
    focusName?: string;
};

useFieldArray focus option, ability to toggle focus on and off with shouldFocus and setting focus by either field index or name.

type FieldArrayPath

type FieldArrayPath<TFieldValues extends FieldValues> = ArrayPath<TFieldValues>;

See ArrayPath

type FieldArrayPathValue

type FieldArrayPathValue<
    TFieldValues extends FieldValues,
    TFieldArrayPath extends FieldArrayPath<TFieldValues>
> = PathValue<TFieldValues, TFieldArrayPath>;

See PathValue

type FieldArrayWithId

type FieldArrayWithId<
    TFieldValues extends FieldValues = FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,
    TKeyName extends string = 'id'
> = FieldArray<TFieldValues, TFieldArrayName> & Record<TKeyName, string>;

useFieldArray returned fields with unique id

type FieldElement

type FieldElement<TFieldValues extends FieldValues = FieldValues> =
    | HTMLInputElement
    | HTMLSelectElement
    | HTMLTextAreaElement
    | CustomElement<TFieldValues>;

type FieldError

type FieldError = {
    type: LiteralUnion<keyof RegisterOptions, string>;
    root?: FieldError;
    ref?: Ref;
    types?: MultipleFieldErrors;
    message?: Message;
};

type FieldErrors

type FieldErrors<T extends FieldValues = FieldValues> = Partial<
    FieldValues extends IsAny<FieldValues> ? any : FieldErrorsImpl<DeepRequired<T>>
> & {
    root?: Record<string, GlobalError> & GlobalError;
};

type FieldErrorsImpl

type FieldErrorsImpl<T extends FieldValues = FieldValues> = {
    [K in keyof T]?: T[K] extends BrowserNativeObject | Blob
        ? FieldError
        : K extends 'root' | `root.${string}`
        ? GlobalError
        : T[K] extends object
        ? Merge<FieldError, FieldErrorsImpl<T[K]>>
        : FieldError;
};

type FieldName

type FieldName<TFieldValues extends FieldValues> =
    IsFlatObject<TFieldValues> extends true
        ? Extract<keyof TFieldValues, string>
        : string;

type FieldNamesMarkedBoolean

type FieldNamesMarkedBoolean<TFieldValues extends FieldValues> = DeepMap<
    DeepPartial<TFieldValues>,
    boolean
>;

type FieldPath

type FieldPath<TFieldValues extends FieldValues> = Path<TFieldValues>;

See Path

type FieldPathByValue

type FieldPathByValue<TFieldValues extends FieldValues, TValue> = {
    [Key in FieldPath<TFieldValues>]: FieldPathValue<
        TFieldValues,
        Key
    > extends TValue
        ? Key
        : never;
}[FieldPath<TFieldValues>];

Type which eagerly collects all paths through a fieldType that matches a give type

Example 1

FieldPathByValue<{foo: {bar: number}, baz: number, bar: string}, number>
  = 'foo.bar' | 'baz'

type FieldPathValue

type FieldPathValue<
    TFieldValues extends FieldValues,
    TFieldPath extends FieldPath<TFieldValues>
> = PathValue<TFieldValues, TFieldPath>;

See PathValue

type FieldPathValues

type FieldPathValues<
    TFieldValues extends FieldValues,
    TPath extends FieldPath<TFieldValues>[] | readonly FieldPath<TFieldValues>[]
> = {} & {
    [K in keyof TPath]: FieldPathValue<
        TFieldValues,
        TPath[K] & FieldPath<TFieldValues>
    >;
};

Type to evaluate the type which the given paths point to.

Example 1

FieldPathValues<{foo: {bar: string}}, ['foo', 'foo.bar']>
  = [{bar: string}, string]

type FieldRefs

type FieldRefs = Partial<Record<InternalFieldName, Field>>;

type FieldValue

type FieldValue<TFieldValues extends FieldValues> = TFieldValues[InternalFieldName];

type FieldValues

type FieldValues = Record<string, any>;

type FormProps

type FormProps<
    TFieldValues extends FieldValues,
    TTransformedValues extends FieldValues | undefined = undefined
> = Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onError' | 'onSubmit'> &
    Partial<{
        control: Control<TFieldValues>;
        headers: Record<string, string>;
        validateStatus: (status: number) => boolean;
        onError: ({
            response,
            error,
        }:
            | {
                  response: Response;
                  error?: undefined;
              }
            | {
                  response?: undefined;
                  error: unknown;
              }) => void;
        onSuccess: ({ response }: { response: Response }) => void;
        onSubmit: TTransformedValues extends FieldValues
            ? FormSubmitHandler<TTransformedValues>
            : FormSubmitHandler<TFieldValues>;
        method: 'post' | 'put' | 'delete';
        children: React.ReactNode | React.ReactNode[];
        render: (props: {
            submit: (e?: React.FormEvent) => void;
        }) => React.ReactNode | React.ReactNode[];
        encType:
            | 'application/x-www-form-urlencoded'
            | 'multipart/form-data'
            | 'text/plain'
            | 'application/json';
    }>;

type FormProviderProps

type FormProviderProps<
    TFieldValues extends FieldValues = FieldValues,
    TContext = any,
    TTransformedValues extends FieldValues | undefined = undefined
> = {
    children: React.ReactNode | React.ReactNode[];
} & UseFormReturn<TFieldValues, TContext, TTransformedValues>;

type FormState

type FormState<TFieldValues extends FieldValues> = {
    isDirty: boolean;
    isLoading: boolean;
    isSubmitted: boolean;
    isSubmitSuccessful: boolean;
    isSubmitting: boolean;
    isValidating: boolean;
    isValid: boolean;
    disabled: boolean;
    submitCount: number;
    defaultValues?: undefined | Readonly<DeepPartial<TFieldValues>>;
    dirtyFields: Partial<Readonly<FieldNamesMarkedBoolean<TFieldValues>>>;
    touchedFields: Partial<Readonly<FieldNamesMarkedBoolean<TFieldValues>>>;
    validatingFields: Partial<Readonly<FieldNamesMarkedBoolean<TFieldValues>>>;
    errors: FieldErrors<TFieldValues>;
};

type FormStateProxy

type FormStateProxy<TFieldValues extends FieldValues = FieldValues> = {
    isDirty: boolean;
    isValidating: boolean;
    dirtyFields: FieldNamesMarkedBoolean<TFieldValues>;
    touchedFields: FieldNamesMarkedBoolean<TFieldValues>;
    validatingFields: FieldNamesMarkedBoolean<TFieldValues>;
    errors: boolean;
    isValid: boolean;
};

type FormStateSubjectRef

type FormStateSubjectRef<TFieldValues extends FieldValues> = Subject<
    Partial<FormState<TFieldValues>> & {
        name?: InternalFieldName;
    }
>;

type FormSubmitHandler

type FormSubmitHandler<TFieldValues extends FieldValues> = (payload: {
    data: TFieldValues;
    event?: React.BaseSyntheticEvent;
    formData: FormData;
    formDataJson: string;
    method?: 'post' | 'put' | 'delete';
}) => unknown | Promise<unknown>;

type GetIsDirty

type GetIsDirty = <TName extends InternalFieldName, TData>(
    name?: TName,
    data?: TData
) => boolean;

type GlobalError

type GlobalError = Partial<{
    type: string | number;
    message: Message;
}>;

type InputValidationRules

type InputValidationRules = typeof INPUT_VALIDATION_RULES;

type InternalFieldErrors

type InternalFieldErrors = Partial<Record<InternalFieldName, FieldError>>;

type InternalFieldName

type InternalFieldName = string;

type InternalNameSet

type InternalNameSet = Set<InternalFieldName>;

type IsAny

type IsAny<T> = 0 extends 1 & T ? true : false;

Checks whether the type is any See https://stackoverflow.com/a/49928360/3406963

type IsEqual

type IsEqual<T1, T2> = T1 extends T2
    ? (<G>() => G extends T1 ? 1 : 2) extends <G>() => G extends T2 ? 1 : 2
        ? true
        : false
    : false;

Checks whether T1 can be exactly (mutually) assigned to T2

type IsFlatObject

type IsFlatObject<T extends object> = Extract<
    Exclude<T[keyof T], NestedValue | Date | FileList>,
    any[] | object
> extends never
    ? true
    : false;

type IsNever

type IsNever<T> = [T] extends [never] ? true : false;

Checks whether the type is never

type KeepStateOptions

type KeepStateOptions = Partial<{
    keepDirtyValues: boolean;
    keepErrors: boolean;
    keepDirty: boolean;
    keepValues: boolean;
    keepDefaultValues: boolean;
    keepIsSubmitted: boolean;
    keepIsSubmitSuccessful: boolean;
    keepTouched: boolean;
    keepIsValidating: boolean;
    keepIsValid: boolean;
    keepSubmitCount: boolean;
}>;

type LiteralUnion

type LiteralUnion<T extends U, U extends Primitive> =
    | T
    | (U & {
          _?: never;
      });

type MaxType

type MaxType = InputValidationRules['max'] | InputValidationRules['maxLength'];

type Merge

type Merge<A, B> = {
    [K in keyof A | keyof B]?: K extends keyof A & keyof B
        ? [A[K], B[K]] extends [object, object]
            ? Merge<A[K], B[K]>
            : A[K] | B[K]
        : K extends keyof A
        ? A[K]
        : K extends keyof B
        ? B[K]
        : never;
};

type Message

type Message = string;

type MinType

type MinType = InputValidationRules['min'] | InputValidationRules['minLength'];

type Mode

type Mode = keyof ValidationMode;

type MultipleFieldErrors

type MultipleFieldErrors = {
    [K in keyof RegisterOptions]?: ValidateResult;
} & {
    [key: string]: ValidateResult;
};

type Names

type Names = {
    mount: InternalNameSet;
    unMount: InternalNameSet;
    array: InternalNameSet;
    watch: InternalNameSet;
    focus?: InternalFieldName;
    watchAll?: boolean;
};

type NativeFieldValue

type NativeFieldValue = string | number | boolean | null | undefined | unknown[];

type NestedValue

type NestedValue<TValue extends object = object> = {
    [$NestedValue]: never;
} & TValue;

Deprecated
to be removed in the next major version

type NonUndefined

type NonUndefined<T> = T extends undefined ? never : T;

type Noop

type Noop = () => void;

type Path

type Path<T> = T extends any ? PathInternal<T> : never;

Type which eagerly collects all paths through a type
Example 1
Path<{foo: {bar: string}}> = 'foo' | 'foo.bar'

type PathString

type PathString = string;

Type alias to string which describes a lodash-like path through an object. E.g. 'foo.bar.0.baz'

type PathValue

type PathValue<T, P extends Path<T> | ArrayPath<T>> = T extends any
    ? P extends `${infer K}.${infer R}`
        ? K extends keyof T
            ? R extends Path<T[K]>
                ? PathValue<T[K], R>
                : never
            : K extends `${ArrayKey}`
            ? T extends ReadonlyArray<infer V>
                ? PathValue<V, R & Path<V>>
                : never
            : never
        : P extends keyof T
        ? T[P]
        : P extends `${ArrayKey}`
        ? T extends ReadonlyArray<infer V>
            ? V
            : never
        : never
    : never;

Type to evaluate the type which the given path points to.

Example 1

PathValue<{foo: {bar: string}}, 'foo.bar'> = string
PathValue<[number, string], '1'> = string

type Primitive

type Primitive = null | undefined | string | number | boolean | symbol | bigint;

type ReadFormState

type ReadFormState = {
    [K in keyof FormStateProxy]: boolean | 'all';
};

type Ref

type Ref = FieldElement;

type RefCallBack

type RefCallBack = (instance: any) => void;

type RegisterOptions

type RegisterOptions<
    TFieldValues extends FieldValues = FieldValues,
    TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
> = Partial<{
    required: Message | ValidationRule<boolean>;
    min: ValidationRule<number | string>;
    max: ValidationRule<number | string>;
    maxLength: ValidationRule<number>;
    minLength: ValidationRule<number>;
    validate:
        | Validate<FieldPathValue<TFieldValues, TFieldName>, TFieldValues>
        | Record<
              string,
              Validate<FieldPathValue<TFieldValues, TFieldName>, TFieldValues>
          >;
    value: FieldPathValue<TFieldValues, TFieldName>;
    setValueAs: (value: any) => any;
    shouldUnregister?: boolean;
    onChange?: (event: any) => void;
    onBlur?: (event: any) => void;
    disabled: boolean;
    deps: FieldPath<TFieldValues> | FieldPath<TFieldValues>[];
}> &
    (
        | {
              pattern?: ValidationRule<RegExp>;
              valueAsNumber?: false;
              valueAsDate?: false;
          }
        | {
              pattern?: undefined;
              valueAsNumber?: false;
              valueAsDate?: true;
          }
        | {
              pattern?: undefined;
              valueAsNumber?: true;
              valueAsDate?: false;
          }
    );

type Resolver

type Resolver<TFieldValues extends FieldValues = FieldValues, TContext = any> = (
    values: TFieldValues,
    context: TContext | undefined,
    options: ResolverOptions<TFieldValues>
) => Promise<ResolverResult<TFieldValues>> | ResolverResult<TFieldValues>;

type ResolverError

type ResolverError<TFieldValues extends FieldValues = FieldValues> = {
    values: {};
    errors: FieldErrors<TFieldValues>;
};

type ResolverResult

type ResolverResult<TFieldValues extends FieldValues = FieldValues> =
    | ResolverSuccess<TFieldValues>
    | ResolverError<TFieldValues>;

type ResolverSuccess

type ResolverSuccess<TFieldValues extends FieldValues = FieldValues> = {
    values: TFieldValues;
    errors: {};
};

type SetFieldValue

type SetFieldValue<TFieldValues extends FieldValues> = FieldValue<TFieldValues>;

type SetFocusOptions

type SetFocusOptions = Partial<{
    shouldSelect: boolean;
}>;

type SetValueConfig

type SetValueConfig = Partial<{
    shouldValidate: boolean;
    shouldDirty: boolean;
    shouldTouch: boolean;
}>;

type Subjects

type Subjects<TFieldValues extends FieldValues = FieldValues> = {
    values: Subject<{
        name?: InternalFieldName;
        type?: EventType;
        values: FieldValues;
    }>;
    array: Subject<{
        name?: InternalFieldName;
        values?: FieldValues;
    }>;
    state: FormStateSubjectRef<TFieldValues>;
};

type SubmitErrorHandler

type SubmitErrorHandler<TFieldValues extends FieldValues> = (
    errors: FieldErrors<TFieldValues>,
    event?: React.BaseSyntheticEvent
) => unknown | Promise<unknown>;

type SubmitHandler

type SubmitHandler<TFieldValues extends FieldValues> = (
    data: TFieldValues,
    event?: React.BaseSyntheticEvent
) => unknown | Promise<unknown>;

type TriggerConfig

type TriggerConfig = Partial<{
    shouldFocus: boolean;
}>;

type UnpackNestedValue

type UnpackNestedValue<T> = T extends NestedValue<infer U>
    ? U
    : T extends Date | FileList | File | Blob
    ? T
    : T extends object
    ? {
          [K in keyof T]: UnpackNestedValue<T[K]>;
      }
    : T;

Deprecated
to be removed in the next major version

type UseControllerProps

type UseControllerProps<
    TFieldValues extends FieldValues = FieldValues,
    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
> = {
    name: TName;
    rules?: Omit<
        RegisterOptions<TFieldValues, TName>,
        'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'
    >;
    shouldUnregister?: boolean;
    defaultValue?: FieldPathValue<TFieldValues, TName>;
    control?: Control<TFieldValues>;
    disabled?: boolean;
};

type UseControllerReturn

type UseControllerReturn<
    TFieldValues extends FieldValues = FieldValues,
    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
> = {
    field: ControllerRenderProps<TFieldValues, TName>;
    formState: UseFormStateReturn<TFieldValues>;
    fieldState: ControllerFieldState;
};

type UseFieldArrayAppend

type UseFieldArrayAppend<
    TFieldValues extends FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>
> = (
    value:
        | FieldArray<TFieldValues, TFieldArrayName>
        | FieldArray<TFieldValues, TFieldArrayName>[],
    options?: FieldArrayMethodProps
) => void;

Append field/fields to the end of your fields and focus. The input value will be registered during this action.

Parameter value

append items or items.

Parameter options

focus options

Remarks

[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/calc-i231d)

Example 1

<button type="button" onClick={() => append({ name: "data" })}>Append</button>
<button type="button" onClick={() => append({ name: "data" }, { shouldFocus: false })}>Append</button>
<button
  type="button"
  onClick={() => append([{ name: "data" }, { name: "data" }])}
>
  Append
</button>

type UseFieldArrayInsert

type UseFieldArrayInsert<
    TFieldValues extends FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>
> = (
    index: number,
    value:
        | FieldArray<TFieldValues, TFieldArrayName>
        | FieldArray<TFieldValues, TFieldArrayName>[],
    options?: FieldArrayMethodProps
) => void;

Insert field/fields at particular position and focus.

Parameter index

insert position

Parameter value

insert field or fields

Parameter options

focus options

Remarks

[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/calc-i231d)

Example 1

<button type="button" onClick={() => insert(1, { name: "data" })}>Insert</button>
<button type="button" onClick={() => insert(1, { name: "data" }, { shouldFocus: false })}>Insert</button>
<button
  type="button"
  onClick={() => insert(1, [{ name: "data" }, { name: "data" }])}
>
  Insert
</button>

type UseFieldArrayMove

type UseFieldArrayMove = (indexA: number, indexB: number) => void;

Move field array by supplying from and to index
Parameter indexA
from index
Parameter indexB
to index
Remarks
[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/calc-i231d)
Example 1
<button type="button" onClick={() => move(0, 1)}>swap</button>

type UseFieldArrayPrepend

type UseFieldArrayPrepend<
    TFieldValues extends FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>
> = (
    value:
        | FieldArray<TFieldValues, TFieldArrayName>
        | FieldArray<TFieldValues, TFieldArrayName>[],
    options?: FieldArrayMethodProps
) => void;

Prepend field/fields to the start of the fields and optionally focus. The input value will be registered during this action.

Parameter value

prepend items or items

Parameter options

focus options

Remarks

[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/calc-i231d)

Example 1

<button type="button" onClick={() => prepend({ name: "data" })}>Prepend</button>
<button type="button" onClick={() => prepend({ name: "data" }, { shouldFocus: false })}>Prepend</button>
<button
  type="button"
  onClick={() => prepend([{ name: "data" }, { name: "data" }])}
>
  Prepend
</button>

type UseFieldArrayProps

type UseFieldArrayProps<
    TFieldValues extends FieldValues = FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,
    TKeyName extends string = 'id'
> = {
    name: TFieldArrayName;
    keyName?: TKeyName;
    control?: Control<TFieldValues>;
    rules?: {
        validate?:
            | Validate<FieldArray<TFieldValues, TFieldArrayName>[], TFieldValues>
            | Record<
                  string,
                  Validate<FieldArray<TFieldValues, TFieldArrayName>[], TFieldValues>
              >;
    } & Pick<RegisterOptions<TFieldValues>, 'maxLength' | 'minLength' | 'required'>;
    shouldUnregister?: boolean;
};

type UseFieldArrayRemove

type UseFieldArrayRemove = (index?: number | number[]) => void;

Remove field/fields at particular position.
Parameter index
index to remove at, or remove all when no index provided.
Remarks
[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/calc-i231d)
Example 1
<button type="button" onClick={() => remove(0)}>Remove</button> <button type="button" onClick={() => remove()} > Remove all </button>

type UseFieldArrayReplace

type UseFieldArrayReplace<
    TFieldValues extends FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>
> = (
    value:
        | FieldArray<TFieldValues, TFieldArrayName>
        | FieldArray<TFieldValues, TFieldArrayName>[]
) => void;

Replace the entire field array values.
Parameter value
the entire field values.
Remarks
[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/calc-i231d)
Example 1
<button type="button" onClick={() => replace([{ name: "data" }, { name: "data" }])} > Replace </button>

type UseFieldArrayReturn

type UseFieldArrayReturn<
    TFieldValues extends FieldValues = FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,
    TKeyName extends string = 'id'
> = {
    swap: UseFieldArraySwap;
    move: UseFieldArrayMove;
    prepend: UseFieldArrayPrepend<TFieldValues, TFieldArrayName>;
    append: UseFieldArrayAppend<TFieldValues, TFieldArrayName>;
    remove: UseFieldArrayRemove;
    insert: UseFieldArrayInsert<TFieldValues, TFieldArrayName>;
    update: UseFieldArrayUpdate<TFieldValues, TFieldArrayName>;
    replace: UseFieldArrayReplace<TFieldValues, TFieldArrayName>;
    fields: FieldArrayWithId<TFieldValues, TFieldArrayName, TKeyName>[];
};

type UseFieldArraySwap

type UseFieldArraySwap = (indexA: number, indexB: number) => void;

Swap field array by supplying from and to index
Parameter indexA
from index
Parameter indexB
to index
Remarks
[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/calc-i231d)
Example 1
<button type="button" onClick={() => swap(0, 1)}>swap</button>

type UseFieldArrayUpdate

type UseFieldArrayUpdate<
    TFieldValues extends FieldValues,
    TFieldArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>
> = (index: number, value: FieldArray<TFieldValues, TFieldArrayName>) => void;

Update field/fields at particular position.
Parameter index
insert position
Parameter value
insert field or fields
Remarks
[API](https://react-hook-form.com/docs/usefieldarray) • [Demo](https://codesandbox.io/s/calc-i231d)
Example 1
<button type="button" onClick={() => update(1, { name: "data" })}>Update</button> <button type="button" onClick={() => update(1, [{ name: "data" }, { name: "data" }])} > Update </button>

type UseFormClearErrors

type UseFormClearErrors<TFieldValues extends FieldValues> = (
    name?:
        | FieldPath<TFieldValues>
        | FieldPath<TFieldValues>[]
        | readonly FieldPath<TFieldValues>[]
        | `root.${string}`
        | 'root'
) => void;

Clear the entire form errors.
Parameter name
the path name to the form field value.
Remarks
[API](https://react-hook-form.com/docs/useform/clearerrors) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-clearerrors-w3ymx)
Example 1
Clear all errors
clearErrors(); // clear the entire form error clearErrors(["name", "name1"]) // clear an array of fields' error clearErrors("name2"); // clear a single field error

type UseFormGetFieldState

type UseFormGetFieldState<TFieldValues extends FieldValues> = <
    TFieldName extends FieldPath<TFieldValues>
>(
    name: TFieldName,
    formState?: FormState<TFieldValues>
) => {
    invalid: boolean;
    isDirty: boolean;
    isTouched: boolean;
    isValidating: boolean;
    error?: FieldError;
};

This method will return individual field states. It will be useful when you are trying to retrieve the nested value field state in a typesafe approach.
Parameter name
the path name to the form field value.
Returns
invalid, isDirty, isTouched and error object
Remarks
[API](https://react-hook-form.com/docs/useform/getfieldstate) • [Demo](https://codesandbox.io/s/getfieldstate-jvekk)
Example 1
// those formState has to be subscribed const { formState: { dirtyFields, errors, touchedFields } } = formState(); getFieldState('name') // Get field state when form state is not subscribed yet getFieldState('name', formState) // It's ok to combine with useFormState const formState = useFormState(); getFieldState('name') getFieldState('name', formState)

type UseFormGetValues

type UseFormGetValues<TFieldValues extends FieldValues> = {
    /**
     * Get the entire form values when no argument is supplied to this function.
     *
     * @remarks
     * [API](https://react-hook-form.com/docs/useform/getvalues) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-getvalues-txsfg)
     *
     * @returns form values
     *
     * @example
     * ```tsx
     * <button onClick={() => getValues()}>getValues</button>
     *
     * <input {...register("name", {
     *   validate: (value, formValues) => formValues.otherField === value;
     * })} />
     * ```
     */
    (): TFieldValues;
    /**
     * Get a single field value.
     *
     * @remarks
     * [API](https://react-hook-form.com/docs/useform/getvalues) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-getvalues-txsfg)
     *
     * @param name - the path name to the form field value.
     *
     * @returns the single field value
     *
     * @example
     * ```tsx
     * <button onClick={() => getValues("name")}>getValues</button>
     *
     * <input {...register("name", {
     *   validate: () => getValues('otherField') === "test";
     * })} />
     * ```
     */
    <TFieldName extends FieldPath<TFieldValues>>(name: TFieldName): FieldPathValue<
        TFieldValues,
        TFieldName
    >;
    /**
     * Get an array of field values.
     *
     * @remarks
     * [API](https://react-hook-form.com/docs/useform/getvalues) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-getvalues-txsfg)
     *
     * @param names - an array of field names
     *
     * @returns An array of field values
     *
     * @example
     * ```tsx
     * <button onClick={() => getValues(["name", "name1"])}>getValues</button>
     *
     * <input {...register("name", {
     *   validate: () => getValues(["fieldA", "fieldB"]).includes("test");
     * })} />
     * ```
     */
    <TFieldNames extends FieldPath<TFieldValues>[]>(
        names: readonly [...TFieldNames]
    ): [...FieldPathValues<TFieldValues, TFieldNames>];
};

type UseFormHandleSubmit

type UseFormHandleSubmit<
    TFieldValues extends FieldValues,
    TTransformedValues extends FieldValues | undefined = undefined
> = (
    onValid: TTransformedValues extends undefined
        ? SubmitHandler<TFieldValues>
        : TTransformedValues extends FieldValues
        ? SubmitHandler<TTransformedValues>
        : never,
    onInvalid?: SubmitErrorHandler<TFieldValues>
) => (e?: React.BaseSyntheticEvent) => Promise<void>;

Validate the entire form. Handle submit and error callback.
Parameter onValid
callback function invoked after form pass validation
Parameter onInvalid
callback function invoked when form failed validation
Returns
callback - return callback function
Remarks
[API](https://react-hook-form.com/docs/useform/handlesubmit) • [Demo](https://codesandbox.io/s/react-hook-form-handlesubmit-ts-v7-lcrtu) • [Video](https://www.youtube.com/watch?v=KzcPKB9SOEk)
Example 1
const onSubmit = (data) => console.log(data); const onError = (error) => console.log(error); <form onSubmit={handleSubmit(onSubmit, onError)} />

type UseFormProps

type UseFormProps<
    TFieldValues extends FieldValues = FieldValues,
    TContext = any
> = Partial<{
    mode: Mode;
    disabled: boolean;
    reValidateMode: Exclude<Mode, 'onTouched' | 'all'>;
    defaultValues: DefaultValues<TFieldValues> | AsyncDefaultValues<TFieldValues>;
    values: TFieldValues;
    errors: FieldErrors<TFieldValues>;
    resetOptions: Parameters<UseFormReset<TFieldValues>>[1];
    resolver: Resolver<TFieldValues, TContext>;
    context: TContext;
    shouldFocusError: boolean;
    shouldUnregister: boolean;
    shouldUseNativeValidation: boolean;
    progressive: boolean;
    criteriaMode: CriteriaMode;
    delayError: number;
}>;

type UseFormRegister

type UseFormRegister<TFieldValues extends FieldValues> = <
    TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
>(
    name: TFieldName,
    options?: RegisterOptions<TFieldValues, TFieldName>
) => UseFormRegisterReturn<TFieldName>;

Register field into hook form with or without the actual DOM ref. You can invoke register anywhere in the component including at useEffect.

Parameter name

the path name to the form field value, name is required and unique

Parameter options

Returns

onChange, onBlur, name, ref, and native contribute attribute if browser validation is enabled.

Remarks

[API](https://react-hook-form.com/docs/useform/register) • [Demo](https://codesandbox.io/s/react-hook-form-register-ts-ip2j3) • [Video](https://www.youtube.com/watch?v=JFIpCoajYkA)

Example 1

// Register HTML native input
<input {...register("input")} />
<select {...register("select")} />

// Register options
<textarea {...register("textarea", { required: "This is required.", maxLength: 20 })} />
<input type="number" {...register("name2", { valueAsNumber: true })} />
<input {...register("name3", { deps: ["name2"] })} />

// Register custom field at useEffect
useEffect(() => {
  register("name4");
  register("name5", { value: '"hiddenValue" });
}, [register])

// Register without ref
const { onChange, onBlur, name } = register("name6")
<input onChange={onChange} onBlur={onBlur} name={name} />

type UseFormRegisterReturn

type UseFormRegisterReturn<
    TFieldName extends InternalFieldName = InternalFieldName
> = {
    onChange: ChangeHandler;
    onBlur: ChangeHandler;
    ref: RefCallBack;
    name: TFieldName;
    min?: string | number;
    max?: string | number;
    maxLength?: number;
    minLength?: number;
    pattern?: string;
    required?: boolean;
    disabled?: boolean;
};

type UseFormReset

type UseFormReset<TFieldValues extends FieldValues> = (
    values?: DefaultValues<TFieldValues> | TFieldValues | ResetAction<TFieldValues>,
    keepStateOptions?: KeepStateOptions
) => void;

Reset at the entire form state.

Parameter values

the entire form values to be reset

Parameter keepStateOptions

keep form state options

Remarks

[API](https://react-hook-form.com/docs/useform/reset) • [Demo](https://codesandbox.io/s/react-hook-form-reset-v7-ts-pu901) • [Video](https://www.youtube.com/watch?v=qmCLBjyPwVk)

Example 1

useEffect(() => {
  // reset the entire form after component mount or form defaultValues is ready
  reset({
    fieldA: "test"
    fieldB: "test"
  });
}, [reset])

// reset by combine with existing form values
reset({
  ...getValues(),
 fieldB: "test"
});

// reset and keep form state
reset({
  ...getValues(),
}, {
  keepErrors: true,
  keepDirty: true
});

type UseFormResetField

type UseFormResetField<TFieldValues extends FieldValues> = <
    TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
>(
    name: TFieldName,
    options?: Partial<{
        keepDirty: boolean;
        keepTouched: boolean;
        keepError: boolean;
        defaultValue: FieldPathValue<TFieldValues, TFieldName>;
    }>
) => void;

Reset a field state and reference.
Parameter name
the path name to the form field value.
Parameter options
keep form state options
Remarks
[API](https://react-hook-form.com/docs/useform/resetfield) • [Demo](https://codesandbox.io/s/priceless-firefly-d0kuv) • [Video](https://www.youtube.com/watch?v=IdLFcNaEFEo)
Example 1
<input {...register("firstName", { required: true })} /> <button type="button" onClick={() => resetField("firstName"))}>Reset</button>

type UseFormReturn

type UseFormReturn<
    TFieldValues extends FieldValues = FieldValues,
    TContext = any,
    TTransformedValues extends FieldValues | undefined = undefined
> = {
    watch: UseFormWatch<TFieldValues>;
    getValues: UseFormGetValues<TFieldValues>;
    getFieldState: UseFormGetFieldState<TFieldValues>;
    setError: UseFormSetError<TFieldValues>;
    clearErrors: UseFormClearErrors<TFieldValues>;
    setValue: UseFormSetValue<TFieldValues>;
    trigger: UseFormTrigger<TFieldValues>;
    formState: FormState<TFieldValues>;
    resetField: UseFormResetField<TFieldValues>;
    reset: UseFormReset<TFieldValues>;
    handleSubmit: UseFormHandleSubmit<TFieldValues, TTransformedValues>;
    unregister: UseFormUnregister<TFieldValues>;
    control: Control<TFieldValues, TContext>;
    register: UseFormRegister<TFieldValues>;
    setFocus: UseFormSetFocus<TFieldValues>;
};

type UseFormSetError

type UseFormSetError<TFieldValues extends FieldValues> = (
    name: FieldPath<TFieldValues> | `root.${string}` | 'root',
    error: ErrorOption,
    options?: {
        shouldFocus: boolean;
    }
) => void;

Set an error for the field. When set an error which is not associated to a field then manual clearErrors invoke is required.
Parameter name
the path name to the form field value.
Parameter error
an error object which contains type and optional message
Parameter options
whether or not to focus on the field
Remarks
[API](https://react-hook-form.com/docs/useform/seterror) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-seterror-nfxxu) • [Video](https://www.youtube.com/watch?v=raMqvE0YyIY)
Example 1
// when the error is not associated with any fields, `clearError` will need to invoke to clear the error const onSubmit = () => setError("serverError", { type: "server", message: "Error occurred"}) <button onClick={() => setError("name", { type: "min" })} /> // focus on the input after setting the error <button onClick={() => setError("name", { type: "max" }, { shouldFocus: true })} />

type UseFormSetFocus

type UseFormSetFocus<TFieldValues extends FieldValues> = <
    TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
>(
    name: TFieldName,
    options?: SetFocusOptions
) => void;

Set focus on a registered field. You can start to invoke this method after all fields are mounted to the DOM.
Parameter name
the path name to the form field value.
Parameter options
input focus behavior options
Remarks
[API](https://react-hook-form.com/docs/useform/setfocus) • [Demo](https://codesandbox.io/s/setfocus-rolus)
Example 1
useEffect(() => { setFocus("name"); }, [setFocus]) // shouldSelect allows to select input's content on focus <button onClick={() => setFocus("name", { shouldSelect: true })}>Focus</button>

type UseFormSetValue

type UseFormSetValue<TFieldValues extends FieldValues> = <
    TFieldName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
>(
    name: TFieldName,
    value: FieldPathValue<TFieldValues, TFieldName>,
    options?: SetValueConfig
) => void;

Set a single field value, or a group of fields value.

Parameter name

the path name to the form field value.

Parameter value

field value

Parameter options

should validate or update form state

Remarks

[API](https://react-hook-form.com/docs/useform/setvalue) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-setvalue-8z9hx) • [Video](https://www.youtube.com/watch?v=qpv51sCH3fI)

Example 1

// Update a single field
setValue('name', 'value', {
  shouldValidate: true, // trigger validation
  shouldTouch: true, // update touched fields form state
  shouldDirty: true, // update dirty and dirty fields form state
});

// Update a group fields
setValue('root', {
  a: 'test', // setValue('root.a', 'data')
  b: 'test1', // setValue('root.b', 'data')
});

// Update a nested object field
setValue('select', { label: 'test', value: 'Test' });

type UseFormStateProps

type UseFormStateProps<TFieldValues extends FieldValues> = Partial<{
    control?: Control<TFieldValues>;
    disabled?: boolean;
    name?:
        | FieldPath<TFieldValues>
        | FieldPath<TFieldValues>[]
        | readonly FieldPath<TFieldValues>[];
    exact?: boolean;
}>;

type UseFormStateReturn

type UseFormStateReturn<TFieldValues extends FieldValues> = FormState<TFieldValues>;

type UseFormTrigger

type UseFormTrigger<TFieldValues extends FieldValues> = (
    name?:
        | FieldPath<TFieldValues>
        | FieldPath<TFieldValues>[]
        | readonly FieldPath<TFieldValues>[],
    options?: TriggerConfig
) => Promise<boolean>;

Trigger field or form validation
Parameter name
provide empty argument will trigger the entire form validation, an array of field names will validate an array of fields, and a single field name will only trigger that field's validation.
Parameter options
should focus on the error field
Returns
validation result
Remarks
[API](https://react-hook-form.com/docs/useform/trigger) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-triggervalidation-forked-xs7hl) • [Video](https://www.youtube.com/watch?v=-bcyJCDjksE)
Example 1
useEffect(() => { trigger(); }, [trigger]) <button onClick={async () => { const result = await trigger(); // result will be a boolean value }}> trigger </button>

type UseFormUnregister

type UseFormUnregister<TFieldValues extends FieldValues> = (
    name?:
        | FieldPath<TFieldValues>
        | FieldPath<TFieldValues>[]
        | readonly FieldPath<TFieldValues>[],
    options?: Omit<
        KeepStateOptions,
        | 'keepIsSubmitted'
        | 'keepSubmitCount'
        | 'keepValues'
        | 'keepDefaultValues'
        | 'keepErrors'
    > & {
        keepValue?: boolean;
        keepDefaultValue?: boolean;
        keepError?: boolean;
    }
) => void;

Unregister a field reference and remove its value.
Parameter name
the path name to the form field value.
Parameter options
keep form state options
Remarks
[API](https://react-hook-form.com/docs/useform/unregister) • [Demo](https://codesandbox.io/s/react-hook-form-unregister-4k2ey) • [Video](https://www.youtube.com/watch?v=TM99g_NW5Gk&feature=emb_imp_woyt)
Example 1
register("name", { required: true }) <button onClick={() => unregister("name")} /> // there are various keep options to retain formState <button onClick={() => unregister("name", { keepErrors: true })} />

type UseFormWatch

type UseFormWatch<TFieldValues extends FieldValues> = {
    /**
     * Watch and subscribe to the entire form update/change based on onChange and re-render at the useForm.
     *
     * @remarks
     * [API](https://react-hook-form.com/docs/useform/watch) • [Demo](https://codesandbox.io/s/react-hook-form-watch-v7-ts-8et1d) • [Video](https://www.youtube.com/watch?v=3qLd69WMqKk)
     *
     * @returns return the entire form values
     *
     * @example
     * ```tsx
     * const formValues = watch();
     * ```
     */
    (): TFieldValues;
    /**
     * Watch and subscribe to an array of fields used outside of render.
     *
     * @remarks
     * [API](https://react-hook-form.com/docs/useform/watch) • [Demo](https://codesandbox.io/s/react-hook-form-watch-v7-ts-8et1d) • [Video](https://www.youtube.com/watch?v=3qLd69WMqKk)
     *
     * @param names - an array of field names
     * @param defaultValue - defaultValues for the entire form
     *
     * @returns return an array of field values
     *
     * @example
     * ```tsx
     * const [name, name1] = watch(["name", "name1"]);
     * ```
     */
    <TFieldNames extends readonly FieldPath<TFieldValues>[]>(
        names: readonly [...TFieldNames],
        defaultValue?: DeepPartial<TFieldValues>
    ): FieldPathValues<TFieldValues, TFieldNames>;
    /**
     * Watch and subscribe to a single field used outside of render.
     *
     * @remarks
     * [API](https://react-hook-form.com/docs/useform/watch) • [Demo](https://codesandbox.io/s/react-hook-form-watch-v7-ts-8et1d) • [Video](https://www.youtube.com/watch?v=3qLd69WMqKk)
     *
     * @param name - the path name to the form field value.
     * @param defaultValue - defaultValues for the entire form
     *
     * @returns return the single field value
     *
     * @example
     * ```tsx
     * const name = watch("name");
     * ```
     */
    <TFieldName extends FieldPath<TFieldValues>>(
        name: TFieldName,
        defaultValue?: FieldPathValue<TFieldValues, TFieldName>
    ): FieldPathValue<TFieldValues, TFieldName>;
    /**
     * Subscribe to field update/change without trigger re-render
     *
     * @remarks
     * [API](https://react-hook-form.com/docs/useform/watch) • [Demo](https://codesandbox.io/s/react-hook-form-watch-v7-ts-8et1d) • [Video](https://www.youtube.com/watch?v=3qLd69WMqKk)
     *
     * @param callback - call back function to subscribe all fields change and return unsubscribe function
     * @param defaultValues - defaultValues for the entire form
     *
     * @returns unsubscribe function
     *
     * @example
     * ```tsx
     * useEffect(() => {
     *   const { unsubscribe } = watch((value) => {
     *     console.log(value);
     *   });
     *   return () => unsubscribe();
     * }, [watch])
     * ```
     */
    (
        callback: WatchObserver<TFieldValues>,
        defaultValues?: DeepPartial<TFieldValues>
    ): Subscription;
};

type UseWatchProps

type UseWatchProps<TFieldValues extends FieldValues = FieldValues> = {
    defaultValue?: unknown;
    disabled?: boolean;
    name?:
        | FieldPath<TFieldValues>
        | FieldPath<TFieldValues>[]
        | readonly FieldPath<TFieldValues>[];
    control?: Control<TFieldValues>;
    exact?: boolean;
};

type Validate

type Validate<TFieldValue, TFormValues> = (
    value: TFieldValue,
    formValues: TFormValues
) => ValidateResult | Promise<ValidateResult>;

type ValidateResult

type ValidateResult = Message | Message[] | boolean | undefined;

type ValidationMode

type ValidationMode = typeof VALIDATION_MODE;

type ValidationModeFlags

type ValidationModeFlags = {
    isOnSubmit: boolean;
    isOnBlur: boolean;
    isOnChange: boolean;
    isOnAll: boolean;
    isOnTouch: boolean;
};

type ValidationRule

type ValidationRule<TValidationValue extends ValidationValue = ValidationValue> =
    | TValidationValue
    | ValidationValueMessage<TValidationValue>;

type ValidationValue

type ValidationValue = boolean | number | string | RegExp;

type ValidationValueMessage

type ValidationValueMessage<
    TValidationValue extends ValidationValue = ValidationValue
> = {
    value: TValidationValue;
    message: Message;
};

type WatchInternal

type WatchInternal<TFieldValues> = (
    fieldNames?: InternalFieldName | InternalFieldName[],
    defaultValue?: DeepPartial<TFieldValues>,
    isMounted?: boolean,
    isGlobal?: boolean
) =>
    | FieldPathValue<FieldValues, InternalFieldName>
    | FieldPathValues<FieldValues, InternalFieldName[]>;

type WatchObserver

type WatchObserver<TFieldValues extends FieldValues> = (
    value: DeepPartial<TFieldValues>,
    info: {
        name?: FieldPath<TFieldValues>;
        type?: EventType;
        values?: unknown;
    }
) => void;

Dependencies (0)

No dependencies.

Peer Dependencies (1)

react

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/react-hook-form.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/react-hook-form)

HTML

<a href="https://www.jsdocs.io/package/react-hook-form"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 23 days ago.
Package analyzed in 4177 ms.
Missing or incorrect documentation? Open an issue for this package.