useForm is custom hook for managing forms with ease. It takes optional arguments. The following example demonstrates all of the arguments along with their default values.

useForm({
  mode: 'onSubmit',
  reValidateMode: 'onChange',
  defaultValues: {},
  resolver: undefined,
  context: undefined,
  criteriaMode: "firstError",
  shouldFocusError: true,
  shouldUnregister: false,
  shouldUseNativeValidation: false,
  delayError: undefined
})

Props

mode: onChange | onBlur | onSubmit | onTouched | all = 'onSubmit'!React Native: compatible with Controller

defaultValues: Record<string, any> = {}

The defaultValues for inputs are used as the initial value when a component is first rendered, before a user interacts with it. It is encouraged that you set defaultValues for all inputs to non-undefined values such as the empty string or null.

You can set an input's default value with defaultValue/defaultChecked (read more from the React doc for Default Values). You can pass defaultValues as an optional argument to useForm() to populate the default values for the entire form, or set values on an individual Controller component via its defaultValue property. If both defaultValue and defaultValues are set, the value from defaultValues will be used.

Rules

• Important: You should provide a proper default value and avoid undefined.

  • undefined is reserved for fallback from inline defaultValue/defaultChecked to hook level defaultValues.

  • undefined value is conflicting with controlled component as default state

• defaultValues are cached on the first render within the custom hook. If you want to reset the defaultValues, you should use the reset api.

• defaultValues will be injected into watch, useWatch, Controller and useController's defaultValue.

• defaultValues will be included in the submission result by default, if this is not the desired behavior use shouldUnregister: true instead which means input values will host within all the fields.

• Avoid including custom object into the defaultValues. eg: moment, luxonas those will lead to unexpected result during internal object clone process.

• There are other options to include form data:

  Copy

  // include hidden input <input {...register("hidden")} type="hidden" /> // register input with value register("hidden", { value: "data" }) // include data onSubmit const onSubmit = (data) => { const output = { ...data, others: "others" } }

  // include hidden input
  <input {...register("hidden")} type="hidden" />
  
  // register input with value
  register("hidden", { value: "data" })
  
  // include data onSubmit
  const onSubmit = (data) => {
    const output = {
      ...data,
      others: "others"
    }
  }
  
  

shouldUnregister: boolean = false

By default, an input value will be retained when input is removed. However, you can set shouldUnregister to true to unregister input during unmount.

• This is a global config that overwrites child-level config, if you want to have individual behavior, then you should set the config at the component or hook level, not at useForm.

• By default shouldUnregister: false: unmounted fields will not be validated by build-in validation.

• By setting shouldUnregister to true at useForm level, defaultValues will not be merged against submission result.

• set shouldUnregister: true will set your form behave more closer as native.

  Form values will be lived inside your inputs itself.

  • input unmount will remove value.

  • input hidden should be applied for hidden data.

  • only registered input will be included as submission data.

  • unmounted input will need to notify at either useForm, or useWatch's useEffect for hook form to verify input is unmounted from the DOM.

    Copy

    const NotWork = () => { const [show, setShow] = React.useState(false); // ❌ won't get notified, need to invoke unregister return {show && <input {...register('test')} />} } const Work = () => { const { show } = useWatch() // ✅ get notified at useEffect return {show && <input {...register('test1')} />} } const App = () => { const [show, setShow] = React.useState(false); const { control } = useForm({ shouldUnregister: true }); return ( <div> // ✅ get notified at useForm's useEffect {show && <input {...register('test2')} />} <NotWork /> <Work control={control} /> </div> ) }

    const NotWork = () => {
      const [show, setShow] = React.useState(false);
      // ❌ won't get notified, need to invoke unregister
      return {show && <input {...register('test')} />}
    }
    
    const Work = () => {
      const { show } = useWatch()
      // ✅ get notified at useEffect
      return {show && <input {...register('test1')} />}
    }
    
    const App = () => {
      const [show, setShow] = React.useState(false);
      const { control } = useForm({ shouldUnregister: true });
      return (
        <div>
          // ✅ get notified at useForm's useEffect
          {show && <input {...register('test2')} />}
          <NotWork />
          <Work control={control} />
        </div>
      )
    }
    
    

shouldUseNativeValidation: boolean = false

This config will enable browser native validation. It will also enable CSS selectors :valid and:invalid making style inputs easier. In fact, you can still use those selectors even the client validation is disabled.

• You can turn on this config and set novalidate at your form and still use those CSS selectors.

• This feature only works for register API, not useController/Controller.

Examples

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

export default function App() {
  const { register, handleSubmit } = useForm({ shouldUseNativeValidation: true });
  const onSubmit = async data => { console.log(data); };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input
        {...register("firstName", { required: "Please enter your first name." })} // custom message
      />
      <input type="submit" />
    </form>
  );
}

resolver: Resolver

This function allows you to use any external validation library such as Yup, Zod, Joi, Superstruct, Vest and many others. The goal is to make sure you can seamlessly integrate whichever validation library you prefer. If you're not using a library, you can always write your own logic to validate your forms.

Props

Rules

• Schema validation focus on the field level for error reporting. Parent level error look is only limited to the direct parent level that is applicable for components such as group checkboxes.

• This function will be cached.

• Re-validation of an input will only occur one field at time during a user’s interaction. The lib itself will evaluate the error object to trigger a re-render accordingly.

• A resolver cannot be used with the built-in validators (e.g.: required, min, etc.)

• When building a custom resolver:

  • Make sure you are returning an object that has both a values and an errors property. Their default values should be an empty object. For example: {}.

  • The keys of the error object should match the name values of your fields.

Examples

import React from 'react';
import { useForm } from 'react-hook-form';
import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from "yup";

const schema = yup.object().shape({
  name: yup.string().required(),
  age: yup.number().required(),
}).required();

export default function App() {
  const { register, handleSubmit } = useForm({
    resolver: yupResolver(schema),
  });

  return (
    <form onSubmit={handleSubmit(d => console.log(d))}>
      <input {...register("name")} />
      <input type="number" {...register("age")} />
      <input type="submit" />
    </form>
  );
};

import React from "react";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import * as z from "zod";

const schema = z.object({
  name: z.string(),
  age: z.number()
});

export default function App() {
  const { register, handleSubmit } = useForm({
    resolver: zodResolver(schema)
  });

  return (
    <form onSubmit={handleSubmit(d => console.log(d)}>
      <input {...register("name")} />
      <input {...register("age")} type="number" />
      <input type="submit" />
    </form>
  );
};

import React from 'react';
import { useForm } from 'react-hook-form';
import { joiResolver } from '@hookform/resolvers/joi';
import Joi from "joi";

const schema = Joi.object({
  name: Joi.string().required(),
  age: Joi.string().required(),
});

export default function App() {
  const { register, handleSubmit } = useForm({
    resolver: joiResolver(schema),
  });

  return (
    <form onSubmit={handleSubmit(d => console.log(d)}>
      <input {...register("name")} />
      <input type="number" {...register("age")} />
      <input type="submit" />
    </form>
  );
};

import React from 'react';
import { useForm } from 'react-hook-form';
import { superstructResolver } from '@hookform/resolvers/superstruct';
import { struct } from 'superstruct';

const schema = struct({
  name: 'string',
  age: 'number',
});

export default function App() {
  const { register, handleSubmit } = useForm({
    resolver: superstructResolver(schema),
  });

  return (
    <form onSubmit={handleSubmit(d => console.log(d))}>
      <input {...register("name")} />
      <input {...register("age")} type="number" />
      <input type="submit" />
    </form>
  );
};

import * as React from 'react';
import { useForm } from 'react-hook-form';
import { vestResolver } from '@hookform/resolvers/vest';
import vest, { test, enforce } from 'vest';

const validationSuite = vest.create((data = {}) => {
  test('username', 'Username is required', () => {
    enforce(data.username).isNotEmpty();
  });

  test('username', 'Must be longer than 3 chars', () => {
    enforce(data.username).longerThan(3);
  });

  test('password', 'Password is required', () => {
    enforce(data.password).isNotEmpty();
  });

  test('password', 'Password must be at least 5 chars', () => {
    enforce(data.password).longerThanOrEquals(5);
  });

  test('password', 'Password must contain a digit', () => {
    enforce(data.password).matches(/[0-9]/);
  });

  test('password', 'Password must contain a symbol', () => {
    enforce(data.password).matches(/[^A-Za-z0-9]/);
  });
});

export default function App() {
  const { register, handleSubmit } = useForm({
    resolver: vestResolver(validationSuite),
  });

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <input {...register("username")} />
      <input {...register("password")} />
      <input type="submit" />
    </form>
  );
};

import * as React from "react";
import { useForm } from "react-hook-form";
import * as Joi from "joi";

const validationSchema = Joi.object({
  username: Joi.string()
    .alphanum()
    .min(3)
    .max(30)
    .required()
});

export default function App() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm({
    context: "context",
    resolver: async (data, context) => {
      const { error, value: values } = validationSchema.validate(data, {
        abortEarly: false,
      });

      if (!error) return { values: values, errors: {} };

      return {
        values: {},
        errors: error.details.reduce(
          (previous, currentError) => ({
            ...previous,
            [currentError.path[0]]: currentError,
          }),
          {},
        ),
      };
    },
  });

  const onSubmit = data => {
    console.log(data)
  };

  return (
    <div className="App">
      <h1>resolver</h1>
      
      <form onSubmit={handleSubmit(onSubmit)}>
        <label>Username</label>
        <input {...register("username")} />
        {errors.username && <p>errors.username.message</p>}
        <input type="submit" />
      </form>
    </div>
  );
};