react-hook-form 7.25.3 → 7.27.1

package/dist/index.esm.mjs

@@ -67,7 +67,67 @@ var omit = (source, key) => {
 };
 
 const HookFormContext = React.createContext(null);
+/**
+ * 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 {@link FormProvider}.
+ *
+ * @remarks
+ * [API](https://react-hook-form.com/api/useformcontext) • [Demo](https://codesandbox.io/s/react-hook-form-v7-form-context-ytudi)
+ *
+ * @returns return all useForm methods
+ *
+ * @example
+ * ```tsx
+ * 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")} />;
+ * }
+ * ```
+ */
 const useFormContext = () => React.useContext(HookFormContext);
+/**
+ * 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 {@link useFormContext}.
+ *
+ * @remarks
+ * [API](https://react-hook-form.com/api/useformcontext) • [Demo](https://codesandbox.io/s/react-hook-form-v7-form-context-ytudi)
+ *
+ * @param props - all useFrom methods
+ *
+ * @example
+ * ```tsx
+ * 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")} />;
+ * }
+ * ```
+ */
 const FormProvider = (props) => (React.createElement(HookFormContext.Provider, { value: omit(props, 'children') }, props.children));
 
 var getProxyFormState = (formState, _proxyFormState, localProxyFormState, isRoot = true) => {
@@ -125,6 +185,36 @@ function useSubscribe(props) {
     }, [props.disabled]);
 }
 
+/**
+ * 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.
+ *
+ * @remarks
+ * [API](https://react-hook-form.com/api/useformstate) • [Demo](https://codesandbox.io/s/useformstate-75xly)
+ *
+ * @param props - include options on specify fields to subscribe. {@link UseFormStateReturn}
+ *
+ * @example
+ * ```tsx
+ * 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 useFormState(props) {
     const methods = useFormContext();
     const { control = methods.control, disabled, name, exact } = props || {};
@@ -182,6 +272,22 @@ var objectHasFunction = (data) => {
     return false;
 };
 
+/**
+ * Custom hook to subscribe to field change and isolate re-rendering at the component level.
+ *
+ * @remarks
+ *
+ * [API](https://react-hook-form.com/api/usewatch) • [Demo](https://codesandbox.io/s/react-hook-form-v7-ts-usewatch-h9i5e)
+ *
+ * @example
+ * ```tsx
+ * const { watch } = useForm();
+ * const values = useWatch({
+ *   name: "fieldName"
+ *   control,
+ * })
+ * ```
+ */
 function useWatch(props) {
     const methods = useFormContext();
     const { control = methods.control, name, defaultValue, disabled, exact, } = props || {};
@@ -213,6 +319,30 @@ function useWatch(props) {
     return value;
 }
 
+/**
+ * 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.
+ *
+ * @remarks
+ * [API](https://react-hook-form.com/api/usecontroller) • [Demo](https://codesandbox.io/s/usecontroller-0o8px)
+ *
+ * @param props - the path name to the form field value, and validation rules.
+ *
+ * @returns field properties, field and form state. {@link UseControllerReturn}
+ *
+ * @example
+ * ```tsx
+ * 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 useController(props) {
     const methods = useFormContext();
     const { name, control = methods.control, shouldUnregister } = props;
@@ -221,7 +351,7 @@ function useController(props) {
         control,
         name,
         defaultValue: get(control._formValues, name, get(control._defaultValues, name, props.defaultValue)),
-        exact: !isArrayField,
+        exact: true,
     });
     const formState = useFormState({
         control,
@@ -283,6 +413,48 @@ function useController(props) {
     };
 }
 
+/**
+ * Component based on `useController` hook to work with controlled component.
+ *
+ * @remarks
+ * [API](https://react-hook-form.com/api/usecontroller/controller) • [Demo](https://codesandbox.io/s/react-hook-form-v6-controller-ts-jwyzw) • [Video](https://www.youtube.com/watch?v=N2UNk_UCVyA)
+ *
+ * @param props - the path name to the form field value, and validation rules.
+ *
+ * @returns provide field handler functions, field and form state.
+ *
+ * @example
+ * ```tsx
+ * 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>
+ *   );
+ * }
+ * ```
+ */
 const Controller = (props) => props.render(useController(props));
 
 var appendErrors = (name, validateAllFieldCriteria, errors, type, message) => validateAllFieldCriteria
@@ -432,7 +604,44 @@ var updateAt = (fieldValues, index, value) => {
     return fieldValues;
 };
 
-const useFieldArray = (props) => {
+/**
+ * A custom hook that exposes convenient methods to perform operations with a list of dynamic inputs that need to be appended, updated, removed etc.
+ *
+ * @remarks
+ * [API](https://react-hook-form.com/api/usefieldarray) • [Demo](https://codesandbox.io/s/react-hook-form-usefieldarray-ssugn)
+ *
+ * @param props - useFieldArray props
+ *
+ * @returns methods - functions to manipulate with the Field Arrays (dynamic inputs) {@link UseFieldArrayReturn}
+ *
+ * @example
+ * ```tsx
+ * 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 useFieldArray(props) {
     const methods = useFormContext();
     const { control = methods.control, name, keyName = 'id', shouldUnregister, } = props;
     const [fields, setFields] = React.useState(control._getFieldArray(name));
@@ -581,7 +790,7 @@ const useFieldArray = (props) => {
         replace: React.useCallback(replace, [updateValues, name, control]),
         fields: React.useMemo(() => fields.map((field, index) => (Object.assign(Object.assign({}, field), { [keyName]: ids.current[index] || generateId() }))), [fields, keyName]),
     };
-};
+}
 
 function createSubject() {
     let _observers = [];
@@ -700,7 +909,9 @@ function unset(object, path) {
             if (currentPathsLength === index &&
                 ((isObject(objectRef) && isEmptyObject(objectRef)) ||
                     (Array.isArray(objectRef) &&
-                        !objectRef.filter((data) => (isObject(data) && !isEmptyObject(data)) || isBoolean(data)).length))) {
+                        !objectRef.filter((data) => (isObject(data) && !isEmptyObject(data)) ||
+                            isBoolean(data) ||
+                            (Array.isArray(data) && data.length)).length))) {
                 previousObjRef ? delete previousObjRef[item] : delete object[item];
             }
             previousObjRef = objectRef;
@@ -970,8 +1181,7 @@ var validateField = async (field, inputValue, validateAllFieldCriteria, shouldUs
         const maxOutput = getValueAndMessage(max);
         const minOutput = getValueAndMessage(min);
         if (!isNaN(inputValue)) {
-            const valueNumber = ref.valueAsNumber ||
-                parseFloat(inputValue);
+            const valueNumber = ref.valueAsNumber || +inputValue;
             if (!isNullOrUndefined(maxOutput.value)) {
                 exceedMax = valueNumber > maxOutput.value;
             }
@@ -1239,7 +1449,8 @@ function createFormControl(props = {}) {
             _subjects.state.next(updatedFormState);
         }
         validateFields[name]--;
-        if (_proxyFormState.isValidating && !validateFields[name]) {
+        if (_proxyFormState.isValidating &&
+            !Object.values(validateFields).some((v) => v)) {
             _subjects.state.next({
                 isValidating: false,
             });
@@ -1617,9 +1828,7 @@ function createFormControl(props = {}) {
             e.persist && e.persist();
         }
         let hasNoPromiseError = true;
-        let fieldValues = _options.shouldUnregister
-            ? cloneObject(_formValues)
-            : Object.assign({}, _formValues);
+        let fieldValues = cloneObject(_formValues);
         _subjects.state.next({
             isSubmitting: true,
         });
@@ -1641,7 +1850,9 @@ function createFormControl(props = {}) {
                 await onValid(fieldValues, e);
             }
             else {
-                onInvalid && (await onInvalid(_formState.errors, e));
+                if (onInvalid) {
+                    await onInvalid(Object.assign({}, _formState.errors), e);
+                }
                 _options.shouldFocusError &&
                     focusFieldBy(_fields, (key) => get(_formState.errors, key), _names.mount);
             }
@@ -1763,9 +1974,10 @@ function createFormControl(props = {}) {
             isSubmitSuccessful: false,
         });
     };
-    const setFocus = (name) => {
+    const setFocus = (name, options = {}) => {
         const field = get(_fields, name)._f;
-        (field.ref.focus ? field.ref : field.refs[0]).focus();
+        const fieldRef = field.refs ? field.refs[0] : field.ref;
+        options.shouldSelect ? fieldRef.select() : fieldRef.focus();
     };
     return {
         control: {
@@ -1831,6 +2043,35 @@ function createFormControl(props = {}) {
     };
 }
 
+/**
+ * Custom hook to mange the entire form.
+ *
+ * @remarks
+ * [API](https://react-hook-form.com/api/useform) • [Demo](https://codesandbox.io/s/react-hook-form-get-started-ts-5ksmm) • [Video](https://www.youtube.com/watch?v=RkXv4AXXC_4)
+ *
+ * @param props - form configuration and validation parameters.
+ *
+ * @returns methods - individual functions to manage the form state. {@link UseFormReturn}
+ *
+ * @example
+ * ```tsx
+ * 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>}
+ *       <input type="submit" />
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
 function useForm(props = {}) {
     const _formControl = React.useRef();
     const [formState, updateFormState] = React.useState({