Skip to content

API.V5

focuses on providing the best DX by simplifying the API.

► React Hook Form V6 is released. If you are planning to upgrade, please read through the Migration Guide to V6.

useForm: Function

By invoking useForm, you will receive the following methods register, unregister, errors, watch, handleSubmit, reset, setError, clearError, setValue, getValues, triggerValidation, control and formState.

useForm also has optional arguments. The following example demonstrates all options' default value.

const { register } = useForm({
  mode: 'onSubmit',
  reValidateMode: 'onChange',
  defaultValues: {},
  validationSchema: undefined, // Note: will be deprecated in the next major version with validationResolver
  validationResolver: undefined,
  validationContext: undefined,
  validateCriteriaMode: "firstErrorDetected",
  submitFocusError: true,
  nativeValidation: false, // Note: version 3 only
})const { register } = useForm<{ firstName: string, lastName: string }>({
  mode: 'onSubmit',
  reValidateMode: 'onChange',
  defaultValues: {},
  validationSchema: undefined, // Note: will be deprecated in the next major version with validationResolver
  validationResolver: undefined,
  validationContext: undefined,
  validateCriteriaMode: "firstErrorDetected",
  submitFocusError: true,
  nativeValidation: false, // Note: version 3 only
})
mode: string = 'onSubmit'React Native: compatible with Controller
NameTypeDescription
onSubmit (Default)stringValidation will trigger on the submit event and invalid inputs will attach onChange event listeners to re-validate them.
onBlurstringValidation will trigger on the blur event.
onChangestringValidation will trigger on the change event with each input, and lead to multiple re-renders. Warning: this often comes with a significant impact on performances.
defaultValues: Record<string, any> = {}React Native: Custom register or using Controller

You can set the input's default value with defaultValue/defaultChecked (read more from the React doc for Default Values) or pass defaultValues as an optional argument to populate default values for the entire form.

Important: defaultValues is cached within the custom hook, if you want to reset defaultValues please use api.

Note: Values defined in defaultValues will be injected into as defaultValue.

Note: defaultValues doesn't auto populate with the manually registered input (eg: register('test')) because the manual register field does not provide the ref to React Hook Form.

CodeSandbox JS
import { useForm } from "react-hook-form";

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

  console.log(watch("example")); // watch input value by passing the name of it

  return (
    {/* "handleSubmit" will validate your inputs before invoking "onSubmit" */}
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* register your input into the hook by invoking the "register" function */}
      <input name="example" defaultValue="test" ref={register} />
      
      {/* include validation with required or other standard HTML validation rules */}
      <input name="exampleRequired" ref={register({ required: true })} />
      {/* errors will return when field validation fails  */}
      {errors.exampleRequired && <span>This field is required</span>}
      
      <input type="submit" />
    </form>
  );
}import { useForm } from "react-hook-form";

type Inputs = {
  example: string,
  exampleRequired: string,
};

export default function App() {
  const { register, handleSubmit, watch, errors } = useForm<Inputs>();
  const onSubmit = data => console.log(data);

  console.log(watch("example")) // watch input value by passing the name of it

  return (
    {/* "handleSubmit" will validate your inputs before invoking "onSubmit" */}
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* register your input into the hook by invoking the "register" function */}
      <input name="example" defaultValue="test" ref={register} />
      
      {/* include validation with required or other standard HTML validation rules */}
      <input name="exampleRequired" ref={register({ required: true })} />
      {/* errors will return when field validation fails  */}
      {errors.exampleRequired && <span>This field is required</span>}
      
      <input type="submit" />
    </form>
  );
}
validationSchema:
Object

Apply form validation rules with Yup at the schema level, please refer to the section.

CodeSandbox
validationResolver:
Function

This callback function allows you to run through any schema or custom validation. The function has the entire form values as argument, and you will need to validate the result and return both values and errors. Read more at section.

Note: This function will be cached inside the hook, you will have to either move the function outside of the component or memorise the function.

validationContext:
Object

This context object will be injected into validationResolver's second argument or Yup validation's context object.

validateCriteriaMode:
firstErrorDetected | all

When set to firstError (default), only first error from each field will be gathered.

When set to all, all errors from each field will be gathered.

CodeSandbox
reValidateMode:
onChange | onBlur | onSubmit

This option allows you to configure when inputs with errors get re-validated (by default, validation is triggered during an input change.) React Native: compatible with Controller

submitFocusError:
boolean = true

When set to true (default) and the user submits a form that fails the validation, it will set focus on the first field with an error.

Note: Only registered fields with a ref will work. Manually registered inputs won't work. eg: register('test') // doesn't work

♦

register: (Ref, RegisterOptions?) => voidReact Native: Custom register or using Controller

This method allows you to register input/select Ref and apply validation rules into React Hook Form.

Validation rules are all based on HTML standard and also allow custom validation.

Important: name is required and unique. Input name also supports dot and bracket syntax, which allows you to easily create nested form fields. Example table is below:

Input NameSubmit Result
name="firstName"{ firstName: 'value'}
name="name.firstName"{ name: { firstName: 'value' } }
name="name.firstName[0]"{ name: { firstName: [ 'value' ] } }

If you working on arrays/array fields, you can assign an input name as name[index]. Check out the Field Array example.

Custom Register

You can also register inputs manually, which is useful when working with custom components and Ref is not accessible. This is actually the case when you are working with React Native or custom component like react-select.

By using a custom register call, you will need to update the input value with , because input is no longer registered with its ref.

register('firstName', { required: true, min: 8 })

Note: If you want the custom registered input to trigger a re-render during its value update, then you should give a type to your registered input.

register({ name: 'firstName', type: 'custom' }, { required: true, min: 8 })

Note: multiple radio inputs with the same name, you want to register the validation to the last input so the hook understand validate them as a group at the end.

Register Options

By selecting the register option, the API table below will get updated.

NameDescriptionCode Examples
ref
React.RefObject		React element ref
<input name="test" ref={register} />
required
boolean		A Boolean which, if true, indicates that the input must have a value before the form can be submitted. You can assign a string to return an error message in the errors object.
CodeSandbox TS
<input
  name="test"
  ref={
    register({
      required: true
    })
  }
/>
maxLength
number		The maximum length of the value to accept for this input.
CodeSandbox TS
<input
  name="test"
  ref={
    register({
      maxLength: 2
    })
  }
/>
minLength
number		The minimum length of the value to accept for this input.
CodeSandbox TS
<input
  name="test"
  ref={
    register({
      minLength: 1
    })
  }
/>
max
number		The maximum value to accept for this input.
CodeSandbox TS
<input
  name="test"
  type="number"
  ref={
    register({
      max: 3
    })
  }
/>
min
number		The minimum value to accept for this input.
CodeSandbox TS
<input
  name="test"
  type="number"
  ref={
    register({
      min: 3
    })
  }
/>
pattern
RegExp		The regex pattern for the input.
CodeSandbox TS
<input
  name="test"
  ref={
    register({
      pattern: /[A-Za-z]{3}/
    })
  }
/>
validate
Function | Object		You can pass a callback function as the argument to validate, or you can pass an object of callback functions to validate all of them. (refer to the examples)
CodeSandbox TS
<input
  name="test"
  ref={
    register({
      validate: value => value === '1'
    })
  }
/>
// object of callback functions
<input
  name="test1"
  ref={
    register({
      validate: {
        positive: value => parseInt(value) > 0,
        lessThanTen: value => parseInt(value) < 10,
        asyncValidate: async () => await fetch(url)
      }
    })
  }
/>

unregister: (name: string | string[]) => void

This method will allow you to unregister a single input or an array of inputs. This is useful when you used a custom register in useEffect and want to unregister it when the component unmounts.

Note: When you unregister an input, its value will no longer be included in the form data that gets submitted.

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

export default function App() {
  const { register, handleSubmit, unregister } = useForm();

  const onSubmit = data => console.log(data);
  
  useEffect(() => {
    register({ name: "customRegister" }, { required: true });
    
    return () => unregister("customRegister"); // unregister input after component unmount
  }, [register])

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input type="text" name="firstName" ref={register} />
      <input type="text" name="lastName" ref={register} />
      <button type="button" onClick={() => unregister("lastName")}>unregister</button>
      <input type="submit" />
    </form>
  );
}import React, { useEffect } from "react";
import { useForm } from "react-hook-form";

interface IFormInputs {
  firstName: string;
  lastName?: string;
}

export default function App() {
  const { register, handleSubmit, unregister } = useForm<IFormInputs>();
  const onSubmit = (data: IFormInputs) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input type="text" name="firstName" ref={register} />
      <input type="text" name="lastName" ref={register} />
      <button type="button" onClick={() => unregister("lastName")}>unregister</button>
      <input type="submit" />
    </form>
  );
};

errors: Record<string, Object>

Object containing form errors and error messages corresponding to each input.

Note: Difference between V3 and V4:

  • V4: Nested objects

    Reason: optional chaining is getting widely adopted and allows better support for types..

    errors?.yourDetail?.firstName;

  • V3: Flatten object

    Reason: simple and easy to access error.

    errors['yourDetail.firstName'];

NameTypeDescription
typestringError Type. eg: required, min, max, minLength
typesRecord<{ string, string | boolean }>This is useful when you want to return all validation errors for a single input. For instance, a password field that is required to have a minimum length and contain a special character. Note that you need to set validateCriteriaMode to'all' for this option to work properly.
messagestring | React.ReactElementIf you registered your input with an error message, then it will be put in this field. Otherwise it's an empty string by default.
refReact.RefObjectReference for your input element.

Note: You can use to help handle your error states

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

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

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("singleErrorInput", { required: true })} />
      {errors.singleErrorInput && "Your input is required"}

      {/* refer to the type of error to display message accordingly */}
      <input {...register("multipleErrorInput", { required: true, maxLength: 50 })} />
      {errors.multipleErrorInput?.type === "required" && "Your input is required"}
      {errors.multipleErrorInput?.type === "maxLength" && "Your input exceed maxLength"}

      {/* register with validation */}
      <input type="number" {...register("numberInput", { min: 50 })} />
      {errors.numberInput && "Your input required to be more than 50"}

      {/* register with validation and error message */}
      <input {...register("errorMessage", { required: "This is required" })} />
      {errors.errorMessage?.message}

      <input type="submit" />
    </form>
  );
}
import * as React from 'react'
import { useForm } from "react-hook-form";

interface IFormInputs {
  singleErrorInput: string
  multipleErrorInput: string
  numberInput: string
}

function App() {
  const { register, formState: { errors }, handleSubmit } = useForm<IFormInputs>();

  const onSubmit = (data: IFormInputs) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label>Error</label>
      <input {...register("singleErrorInput", { required: true })} />
      {errors.singleErrorInput && <p>Your input is required</p>}

      <label>Error with type check</label>
      <input {...register("multipleErrorInput", { required: true, minLength: 5 })} />
      {errors.multipleErrorInput?.type === "required" && (
        <p>Your input is required</p>
      )}
      {errors.multipleErrorInput?.type === "minLength" && (
        <p>Your input must be larger then 3 characters</p>
      )}

      <label>Error with value</label>
      <input type="number" {...register("numberInput", { min: 50 })} />
      {errors.numberInput && <p>Your input required to be more than 50</p>}

      <input type="submit" />
    </form>
  );
}
CodeSandbox JS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, errors, handleSubmit } = useForm({
    // by setting validateCriteriaMode to 'all', 
    // all validation errors for single field will display at once
    validateCriteriaMode: "all"
  });
  const onSubmit = data => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input
        type="password"
        name="password"
        ref={register({ required: true, minLength: 10, pattern: /\d+/ })}
      />
      {/* without enter data for the password input will result both messages to appear */}
      {errors?.password?.types?.required && <p>password required</p>}
      {errors?.password?.types?.minLength && <p>password minLength 10</p>}
      {errors?.password?.types?.pattern && <p>password number only</p>}

      <input type="submit" />
    </form>
  );
}
import * as React from "react";
import { useForm } from "react-hook-form";

interface IFormInputs {
  password: string
}

export default function App() {
  const { register, errors, handleSubmit } = useForm<IFormInputs>({
    // by setting validateCriteriaMode to 'all',
    // all validation errors for single field will display at once
    validateCriteriaMode: "all",
    mode: "onChange"
  });

  const onSubmit = (data: IFormInputs) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label>Password</label>
      <input
        type="password"
        name="password"
        ref={register({ required: true, minLength: 10, pattern: /d+/gi })}
      />
      {/* without enter data for the password input will result both messages to appear */}
      {errors?.password?.types?.required && <p>password required</p>}
      {errors?.password?.types?.minLength && <p>password minLength 10</p>}
      {errors?.password?.types?.pattern && <p>password number only</p>}

      <input type="submit" />
    </form>
  );
}

watch: (names?: string | string[]) => anyVideo

This will watch specified inputs and return their values. It is useful for determining what to render.

  • When defaultValue is not defined, the first render of watch will return undefined because it is called before register, but you can set the defaultValue as the second argument to return value.

  • However, if defaultValues was initialised in useForm as argument, then the first render will return what's provided in defaultValues.

TypeDescriptionExampleReturn
stringWatch input value by name (similar to lodash get function)watch('inputName')
watch('inputName', 'value')		any
string[]Watch multiple inputswatch(['inputName1'])
watch(['field1'], { field1: '1' })		{ [key:string] : any }
undefinedWatch all inputswatch()
watch(undefined, { field: '1' })		{ [key:string] : any }
CodeSandbox JS
import React from "react";
import { useForm } from "react-hook-form";

function App() {
  const { register, watch, errors, handleSubmit } = useForm();
  const watchShowAge = watch("showAge", false); // you can supply default value as second argument
  const watchAllFields = watch(); // when pass nothing as argument, you are watching everything
  const watchFields = watch(["showAge", "number"]); // you can also target specific fields by their names

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

  return (
    <>
      <form onSubmit={handleSubmit(onSubmit)}>
        <input type="checkbox" name="showAge" ref={register} />
        
        {/* based on yes selection to display Age Input*/}
        {watchShowAge && <input type="number" name="age" ref={register({ min: 50 })} />}
        
        <input type="submit" />
      </form>
    </>
  );
}
import React from "react";
import { useForm } from "react-hook-form";

interface IFormInputs {
  name: string
  showAge: boolean
  age: number
}

function App() {
  const { register, watch, errors, handleSubmit } = useForm<IFormInputs>();
  const watchShowAge = watch("showAge", false); // you can supply default value as second argument
  const watchAllFields = watch(); // when pass nothing as argument, you are watching everything
  const watchFields = watch(["showAge", "number"]); // you can also target specific fields by their names

  const onSubmit = (data: IFormInputs) => console.log(data);

  return (
    <>
      <form onSubmit={handleSubmit(onSubmit)}>
        <input
          name="name"
          ref={register({ required: true, maxLength: 50 })}
        />
        <input type="checkbox" name="showAge" ref={register} />
        {/* based on yes selection to display Age Input*/}
        {watchShowAge && (
          <>
            <input type="number" name="age" ref={register({ min: 50 })} />
          </>
        )}
        <input type="submit" />
      </form>
    </>
  );
}
import React from "react";
import { useForm } from "react-hook-form";

type Inputs = {
  key1: string;
  key2: number;
  key3: {
    key1: number;
    key2: boolean;
  };
};

export default function App(props) {
  const { watch } = useForm<FormValues>;

  watch();
  // function watch(): FormValues
  watch({ nest: true });
  // function watch(option: { nest: boolean; }): FormValues
  watch("key1");
  // function watch<"key1">(field: "key1", defaultValue?: string | undefined): string
  watch("key1", "test");
  // function watch<"key1">(field: "key1", defaultValue?: string | undefined): string
  watch("key1", true);
  // ❌: type error
  watch("key3.key1");
  // function watch<unknown>(field: string, defaultValue?: unknown): unknown
  watch("key3.key1", 1);
  // function watch<1>(field: string, defaultValue?: 1 | undefined): number
  watch("key3.key1", "test");
  // function watch<"key3.key1", "test">(field: "key3.key1", defaultValue?: string | undefined): string
  watch("key3.key2", true);
  // function watch<true>(field: string, defaultValue?: true | undefined): boolean
  watch(["key1", "key2"]);
  // function watch<"key1" | "key2">(fields: ("key1" | "key2")[], defaultValues?: DeepPartial<Pick<FormValues, "key1" | "key2">> | undefined): Pick<FormValues, "key1" | "key2">
  watch(["key1", "key2"], { key1: "test" });
  // function watch<"key1" | "key2">(fields: ("key1" | "key2")[], defaultValues?: DeepPartial<Pick<FormValues, "key1" | "key2">> | undefined): Pick<FormValues, "key1" | "key2">
  watch(["key1", "key2"], { key1: "test", key2: true });
  // ❌: type error
  watch(["key1", "key3.key1"], { key1: "string" });
  // function watch(fields: string[], defaultValues?: DeepPartial<FormValues> | undefined): DeepPartial<FormValues>
  watch(["key1", "key3.key1"], { test: "string" });
  // ❌: type error
  watch<string, FormData["key3"]["key1"]>("key3.key1");
  //  => string
  watch<string, FormData["key3"]["key2"]>("key3.key2");
  //  => string
  
  return <form />;
}
CodeSandbox TS
import * as React from "react";
import { useForm, useFieldArray, ArrayField } from "react-hook-form";

function App() {
  const { register, control, handleSubmit, watch } = useForm();
  const { fields, remove, append } = useFieldArray({
    name: "test",
    control
  });
  const onSubmit = (data: FormValues) => console.log(data);
  
  console.log(watch("test")); 

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {fields.map((field, index) => {
        return (
          <input
            key={field.id}
            name={`test[${index}].firstName`}
            defaultValue={field.firstName}
            ref={register()}
          />
        );
      })}
      <button
        type="button"
        onClick={() =>
          append({
            firstName: "bill" + renderCount,
            lastName: "luo" + renderCount
          })
        }
      >
        Append
      </button>
    </form>
  );
}

handleSubmit: (data: Object, e: Event) => () => void

This function will pass the form data when form validation is successful and can be invoked remotely as well.

handleSubmit(onSubmit)()

Note: You can pass an async function for asynchronous validation. eg:

handleSubmit(async (data) => await fetchAPI(data))

CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, handleSubmit } = useForm();
  const onSubmit = (data, e) => {
    console.log("Submit event", e);
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input name="firstName" ref={register} />
      <input name="lastName" ref={register} />
      <button type="submit">Submit</button>
    </form>
  );
}

reset: (values?: Record<string, any>, omitResetState: OmitResetState = {}) => void

This function will reset the fields' values and errors within the form. By supply omitResetState, you have the freedom to only reset specific piece of state. You can pass values as an optional argument to reset your form into assigned default values.

Note: For controlled components like React-Select which don't expose ref, you will have to reset the input value manually through or using to wrap around your controlled component.

Note: You will need to supply defaultValues at useForm to reset Controller components' value.

CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, handleSubmit, reset } = useForm();
  const onSubmit = (data, e) => {};
  
  useEffect(async () => {
    const result = await fetch('./api/formValues.json'); // result: { firstName: 'test', lastName: 'test2' }
    reset(result); // asynchronously reset your form values
  }, [reset])

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input name="firstName" ref={register({ required: true })} />
      <input name="lastName" ref={register} />
      <input type="submit" />
      <input type="reset" /> // standard reset button
      <input type="button" onClick={reset} />
      <input type="button" onClick={() => reset({ firstName: "bill" }); }} /> // reset form with values
      <input type="button" onClick={() => {
          reset({
            firstName: "bill"
          }, {
            errors: true, // errors will not be reset 
            dirtyFields: true, // dirtyFields will not be reset
            dirty: true, // dirty will not be reset
            isSubmitted: false,
            touched: false,
            isValid: false,
            submitCount: false,
          });
        }}
      />
    </form>
  );
}
CodeSandbox JS
import { useForm, Controller } from "react-hook-form";
import { TextField } from "@material-ui/core";

export default function App() {
  const { register, handleSubmit, reset, setValue, control } = useForm();
  const onSubmit = data => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Controller 
        as={TextField} 
        name="firstName"
        control={control} 
        rules={ required: true } 
        defaultValue=""
      />
      <Controller 
        as={TextField} 
        name="lastName"
        control={control}
        defaultValue="" 
      />
      
      <input type="submit" />
      <input type="button" onClick={reset} />
      <input
        type="button"
        onClick={() => {
          reset({
            firstName: "bill",
            lastName: "luo"
          });
        }}
      />
    </form>
  );
}
import { useForm, Controller } from "react-hook-form";
import { TextField } from "@material-ui/core";

interface IFormInputs {
  firstName: string
  lastName: string
}

export default function App() {
  const { register, handleSubmit, reset, setValue, control } = useForm<IFormInputs>();
  const onSubmit = (data: IFormInputs) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Controller 
        as={TextField} 
        name="firstName"
        control={control} 
        rules={ required: true } 
        defaultValue=""
      />
      <Controller 
        as={TextField} 
        name="lastName"
        control={control}
        defaultValue="" 
      />
      
      <input type="submit" />
      <input type="button" onClick={reset} />
      <input
        type="button"
        onClick={() => {
          reset({
            firstName: "bill",
            lastName: "luo"
          });
        }}
      />
    </form>
  );
}
CodeSandbox TS
import React, { useEffect } from "react";
import { useForm } from "react-hook-form";

const defaultValues = {
  firstName: "bill",
  lastName: "luo"
};

export default function App() {
  const { register, reset, watch, setValue } = useForm({
    defaultValues
  });
  const values = watch();

  useEffect(() => {
    register({ name: "firstName" }, { required: true });
    register({ name: "lastName" });
  }, [register]);

  return (
    <form>
      <input
        name="firstName"
        onChange={e => setValue("firstName", e.target.value)}
        value={values.firstName}
        placeholder="First Name"
      />
      <input
        name="lastName"
        onChange={e => setValue("lastName", e.target.value)}
        value={values.lastName}
        placeholder="Last Name"
      />
      <button
        type="button"
        onClick={() => {
          reset(defaultValues);
        }}
      >
        Reset
      </button>
    </form>
  );
}

setError:
(name: string | ManualFieldError[], type?: string | Object, message?: string | React.ReactElement) => void

The function allows you to manually set one or multiple errors.

Note: This method will not persist the error and block the submit action. It's more useful during handleSubmit function when you want to give error feedback to the users after async validation.

CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, errors, setError, clearError } = useForm();

  return (
    <form>
      <input
        name="username"
        onChange={e => {
          const value = e.target.value;
          // this will clear error by only pass the name of field
          if (value === "bill") return clearError("username");
          // set an error with type and message
          setError("username", "notMatch", "please choose a different username");
        }}
        ref={register}
      />
      {errors.username && errors.username.message}
    </form>
  );
}
CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, errors, setError } = useForm();

  return (
    <form>
      <input name="username" ref={register} />
      {errors.username && errors.username.message}
      
      <input name="lastName" ref={register} />
      {errors.lastName && errors.lastName.message}
      
      <button type="button" onClick={() => {
        setError([
          {
            type: "required",
            name: "lastName",
            message: "This is required.",
          },
          {
            type: "minLength",
            name: "username",
            message: "Minlength is 10",
          },
        ]);
      }}>
        Set Errors for a single field
      </button>
    </form>
  );
}
CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, setError } = useForm({
    validateCriteriaMode: "all" // you will need to enable validate all criteria mode
  });

  return (
    <form>
      <input name="username" ref={register} />
      {errors.username && errors.username.types && (
        <p>{errors.username.types.required}</p>
      )}
      {errors.username && errors.username.types && (
        <p>{errors.username.types.minLength}</p>
      )}

      <button
        type="button"
        onClick={() =>
          setError("username", {
            required: "This is required",
            minLength: "This is minLength"
          })
        }
      >
        Trigger
      </button>
    </form>
  );
}

clearError: (name?: string | string[]) => void

  • undefined: reset all errors

  • string: reset single error

  • string[]: reset multiple errors

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

export default () => {
  const { clearError, errors, register } = useForm();

  return (
    <form>
      <input name="firstName" ref={register({ required: true })} />
      {errors.firstName && "This is required"}
      <input name="lastName" ref={register({ required: true })} />
      {errors.lastName && "This is required"}

      <button type="button" onClick={() => clearError("firstName")}>
        Clear
      </button>
      <button
        type="button"
        onClick={() => clearError(["firstName", "lastName"])}
      >
        Clear Multiple
      </button>
      <button type="button" onClick={() => clearError()}>
        Clear All
      </button>
    </form>
  );
};

setValue:

(name: string, value: any, shouldValidate?: boolean) => void
(Record<Name, any>[], shouldValidate?: boolean) => void

This function allows you to dynamically set registered input/select value. At the same time, it tries to avoid re-rendering when it's not necessary. Only the following conditions will trigger a re-render:

  • When an error is triggered by a value update

  • When an error is corrected by a value update

  • When setValue is invoked for the first time and formState dirty is set to true

  • When setValue is invoked and formState touched is updated

Note: By invoking this method, formState will set the input to touched.

You can also set the shouldValidate parameter to truein order to trigger a field validation. eg: setValue('name', 'value', true)

CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, setValue } = useForm();

  return (
    <form>
      <input name="test" ref={register} />
      <input name="test1" ref={register} />
      <input name="object.firstName" ref={register} />
      <input name="array[0].firstName" ref={register} />
      <button type="button" onClick={() => {
        // manually set the "test" field with value "bill"
        setValue("test", "bill")
        
        // set multiple values
        setValue([
          { test : "1", },
          { test1 : "2", },
        ])
        
        // set value as object or array
        setValue("object", { firstName: "test" })
        setValue("array", [{ firstName: "test" }])
      }}>SetValue</button>
    </form>
  );
}import { useForm } from "react-hook-form";

type FormValues = {
  string: string;
  number: number;
  object: {
    number: number;
    boolean: boolean;
  };
  array: {
    string: string;
    boolean: boolean;
  }[];
};

export default function App() {
  const { setValue } = useForm<FormValues>();
  
  setValue("string", "test");
  // function setValue<"string", string>(name: "string", value: string, shouldValidate?: boolean | undefined): void
  setValue("number", 1);
  // function setValue<"number", number>(name: "number", value: number, shouldValidate?: boolean | undefined): void
  setValue("number", "error");
  
  return <form />;
}

getValues: (payload?: { nest: boolean } | string) => Object

This function will return the entire form data, and it's useful when you want to retrieve form values.

  • By default getValues() will return form data in a flat structure. eg: { test: 'data', test1: 'data1'}

  • Working on the defined form fields, getValues({ nest: true }) will return data in a nested structure according to input name. eg: { test: [1, 2], test1: { data: '23' } }

CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, getValues } = useForm();

  return (
    <form>
      <input name="test" ref={register} />
      <input name="test1" ref={register} />

      <button
        type="button"
        onClick={() => {
          const values = getValues();
          const singleValue = getValues("test");
          const nestedObjectValue = getValues({ nest: true });
        }}
      >
        Get Values
      </button>
    </form>
  );
}import { useForm } from "react-hook-form";

// Flat input values
type Inputs = {
  key1: string;
  key2: number;
  key3: boolean;
  key4: Date;
};

export default function App() {
  const { register, getValues } = useForm<Inputs>();
  
  getValues();
  // function getValues(): Inputs
  getValues({ nest: true });
  // function getValues<true>(payload: {
  //     nest: true;
  // }): FormValues
  getValues({ nest: false });
  // function getValues<false>(payload: {
  //     nest: false;
  // }): FormValues

  return <form />;
}

// Nested input values
type Inputs1 = {
  key1: string;
  key2: number;
  key3: {
    key1: number;
    key2: boolean;
  };
  key4: string[];
};

export default function Form() {
  const { register, getValues } = useForm<Inputs1>();
  
  getValues();
  // function getValues(): Record<string, unknown>
  getValues({ nest: true });
  // function getValues<true>(payload: {
  //     nest: true;
  // }): FormValues
  getValues({ nest: false });
  // function getValues<false>(payload: {
  //     nest: false;
  // }): Record<string, unknown>
  getValues("key1");
  // function getValues<"key1", unknown>(payload: "key1"): string
  getValues("key2");
  // function getValues<"key2", unknown>(payload: "key2"): number
  getValues("key3.key1");
  // function getValues<"key3.key1", unknown>(payload: "key3.key1"): unknown
  getValues<string, number>("key3.key1");
  // function getValues<string, number>(payload: string): number
  getValues<string, boolean>("key3.key2");
  // function getValues<string, boolean>(payload: string): boolean
  getValues("key4");
  // function getValues<"key4", unknown>(payload: "key4"): string[]

  return <form />;
}

triggerValidation: (payload?: string | string[]) => Promise<boolean>

To manually trigger an input/select validation in the form.

Note: When validation fails, the errors object will be updated.

CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, triggerValidation, errors } = useForm();
  console.log(errors);

  return (
    <form>
      <input name="firstName" ref={register({ required: true })} />
      <input name="lastName" ref={register({ required: true })} />
      <button type="button" onClick={() => { triggerValidation("lastName"); }}>Trigger</button>
      <button type="button" onClick={() => { triggerValidation(["firstName", "lastName"]); }}>Trigger Multiple</button>
      <button type="button" onClick={() => { triggerValidation(); }}>Trigger All</button>
      <button
        type="button"
        onClick={async () => {
          const result = await triggerValidation("lastName");
          if (result) { console.log("valid input") }
        }}
      >
        Trigger with result
      </button>
    </form>
  );
}

control: Object

This object is contains methods for registering components into React Hook Form.

CodeSandbox TS
import { useForm, Controller } from "react-hook-form";
import { TextField } from "@material-ui/core";

function App() {
  const { control, handleSubmit } = useForm();

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

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Controller
        as={TextField}
        name="firstName"
        control={control}
        defaultValue=""
      />
      
      <input type="submit" />
    </form>
  );
}

formState: Object

This object contain information about the form state.

Important: formState is wrapped with Proxy to improve render performance, so make sure you invoke or read it before render in order to enable the state update. This reduces re-render feature only applies to the Web platform due to a lack of support on Proxy at React Native.

NameTypeDescription
dirtybooleanSet to true after a user interacted with any of the inputs.
dirtyFieldsSetA unique set of user modified fields.
isSubmittedbooleanSet true after a user submitted the form. After a form's submission, its' state will remain submitted until invoked with reset method.
touchedobjectAn object containing all the inputs the user has interacted with.
isSubmittingbooleantrue if the form is currently being submitted. false otherwise.
submitCountnumberNumber of times the form was submitted.
isValidboolean
Set to true if the form doesn't have any error.

Note: isValid is affected by mode. This state is only applicable with onChange and onBlur mode.

CodeSandbox TS
import { useForm } from "react-hook-form";

export default function App() {
  const { register, handleSubmit, errors, formState } = useForm();
  const onSubmit = data => console.log(data);
  // Read the formState before render to subscribe the form state through the Proxy
  const { dirty, isSubmitting, touched, submitCount } = formState;
  
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input name="test" ref={register} />
      <input type="submit" />
    </form>
  );
}

Controller: Component

React Hook Form embraces uncontrolled components and native inputs, however it's hard to avoid working with external controlled component such as React-Select, AntD and MUI. This wrapper component will make it easier for you to work with them.

Every prop you pass to the Controller component will be forwarded to the component instance you provided with the as prop. For instance, if you have a custom Switch component that requires a label prop, you can pass it to the Controller component directly and it will take care of forwarding the prop for you. The name prop will be used mainly to access the value through the form later.

NameTypeRequiredDescription
namestring✓Unique name of your input.
asReact.ElementType | string✓Controlled component. eg: as="input", as={<TextInput />} or as={TextInput}.
controlObjectcontrol object is from invoking useForm. it's optional if you are using FormContext.
defaultValueanyThe same as uncontrolled component's defaultValue, when supply boolean value, it will be treated as checkbox input.

Note: you will need to supply either defaultValue or defaultValues at useForm

Note: If your form will invoke reset with default values, you will need to provide defaultValues at useForm level instead of set inline defaultValue.

rulesObjectValidation rules according to register. This object will be cached inside Controller.
onChange(args: any | EventTarget) => anyThis prop allows you to customize the return value, make sure you aware the shape of the external component value props. value or checked attribute will be read when payload's shape is an object which contains type attribute.
onChange={{([ event ]) => event.target.value}}
onChange={{([ { checked } ]) => ({ checked })}}
onChangeNamestringThis prop allows you to target a specific event name for onChange, eg: when onChange event is named onTextChange
onFocus() => void

This callback allows the custom hook to focus on the input when there is an error. This function is applicable for both React and React-Native components as long as they can be focused.

Here is a working example with MUI.

onBlurNamestringThis prop allows you to target a specific event name for onBlur, eg: when onBlur event is named onTextBlur
valueNamestringThis prop allows you to support inputs that doesn't use a prop called value. eg: checked, selected and etc.
CodeSandbox JS
import Select from "react-select";
import { TextField } from "@material-ui/core";
import { useForm, Controller } from "react-hook-form";

const options = [
  { value: "chocolate", label: "Chocolate" },
  { value: "strawberry", label: "Strawberry" },
  { value: "vanilla", label: "Vanilla" },
];

function App() {
  const { handleSubmit, control } = useForm();

  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      <Controller as={TextField} name="TextField" control={control} defaultValue="" />
      
      <Controller
        as={<Select options={options} />}
        control={control}
        rules={{ required: true }}
        onChange={([selected]) => {
          // Place your logic here
          return selected;
        }}
        name="reactSelect"
        defaultValue={{ value: "chocolate" }}
      />
      
      <button>submit</button>
    </form>
  );
}
import ReactDatePicker from "react-datepicker";
import { TextField } from "@material-ui/core";
import { useForm, Controller } from "react-hook-form";

type FormValues = {
  ReactDatepicker: string;
} 

function App() {
  const { handleSubmit, control } = useForm<FormValues>();

  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      <Controller
        control={control}
        name="ReactDatepicker"
        render={({ field: { onChange, onBlur, value, ref } }) => (
          <ReactDatePicker
            onChange={onChange} // send value to hook form
            onBlur={onBlur} // notify when input is touched/blur
            selected={value}
          />
        )}
      />
      
      <input type="submit" />
    </form>
  );
}
Expo TS
import { Text, View, TextInput, Button, Alert } from "react-native";
import { useForm, Controller } from "react-hook-form";

export default function App() {
  const { control, handleSubmit, formState: { errors } } = useForm({
    defaultValues: {
      firstName: '',
      lastName: ''
    }
  });
  const onSubmit = data => console.log(data);

  return (
    <View>
      <Controller
        control={control}
        rules={{
         required: true,
        }}
        render={({ field: { onChange, onBlur, value } }) => (
          <TextInput
            style={styles.input}
            onBlur={onBlur}
            onChangeText={onChange}
            value={value}
          />
        )}
        name="firstName"
      />
      {errors.firstName && <Text>This is required.</Text>}

      <Controller
        control={control}
        rules={{
         maxLength: 100,
        }}
        render={({ field: { onChange, onBlur, value } }) => (
          <TextInput
            style={styles.input}
            onBlur={onBlur}
            onChangeText={onChange}
            value={value}
          />
        )}
        name="lastName"
      />

      <Button title="Submit" onPress={handleSubmit(onSubmit)} />
    </View>
  );
}

ErrorMessage: Component

A simple component to render associated input's error message.

NameTypeRequiredDescription
namestring✓associated field name.
errorsobjecterrors object from React Hook Form. It's optional if you are using FormContext.
messagestring | React.ReactElementinline error message.
asReact.ElementType | stringWrapper component or HTML tag. eg: as="span" or as={<Text />}
children({ message: string | React.ReactElement, messages?: Object}) => anyThis is a render prop for rendering error message or messages.

Note: you need to set validateCriteriaMode to 'all' for using messages.

CodeSandbox JS
import { useForm, ErrorMessage } from "react-hook-form";

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

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input name="singleErrorInput" ref={register({ required: "This is required." })} />
      <ErrorMessage errors={errors} name="singleErrorInput" />
      
      <ErrorMessage errors={errors} name="singleErrorInput">
        {({ message }) => <p>{message}</p>}
      </ErrorMessage>
      
      <input name="name" ref={register({ required: true })} />
      <ErrorMessage errors={errors} name="name" message="This is required" />
      
      <input type="submit" />
    </form>
  );
}
import { useForm, ErrorMessage } from "react-hook-form";

interface FormInputs {
  singleErrorInput: string
}

export default function App() {
  const { register, errors, handleSubmit } = useForm<FormInputs>();
  const onSubmit = (data: FormInputs) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input name="singleErrorInput" ref={register({ required: "This is required." })} />
      <ErrorMessage errors={errors} name="singleErrorInput" />
      
      <ErrorMessage errors={errors} name="singleErrorInput">
        {({ message }) => <p>{message}</p>}
      </ErrorMessage>
      
      <input name="name" ref={register({ required: true })} />
      <ErrorMessage errors={errors} name="name" message="This is required" />
      
      <input type="submit" />
    </form>
  );
}
CodeSandbox TS
import { useForm, ErrorMessage } from "react-hook-form";

export default function App() {
  const { register, errors, handleSubmit } = useForm({
    validateCriteriaMode: "all"
  });
  const onSubmit = data => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input
        name="multipleErrorInput"
        ref={register({
          required: "This is required.",
          pattern: {
            value: /d+/,
            message: "This input is number only."
          },
          maxLength: {
            value: 10,
            message: "This input exceed maxLength."
          }
        })}
      />
      <ErrorMessage errors={errors} name="multipleErrorInput">
        {({ messages }) =>
          messages &&
          Object.entries(messages).map(([type, message]) => (
            <p key={type}>{message}</p>
          ))
        }
      </ErrorMessage>

      <input type="submit" />
    </form>
  );
}

useFormContext: Component

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.

You need to wrap your form with the FormContext provider component for useFormContext to work properly.

NameTypeDescription
...propsObjectAccept all useForm methods.

Note: invoking useFormContext will give you all of the useForm hook functions.

CodeSandbox TS
import { useForm, FormContext, useFormContext } from "react-hook-form";

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

  return (
    <FormContext {...methods} > // pass all methods into the context
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <NestedInput />
        <input type="submit" />
      </form>
    </FormContext>
  );
}

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

useFieldArray:
({ control?: Control, name: string, keyName?: string = 'id' }) => objectVideo

Custom hook for working with uncontrolled Field Arrays (dynamic inputs). The motivation is to provide better user experience and form performance. You can watch this short video to compare controlled vs uncontrolled Field Array.

This hook provides the following object and functions.

function Test() {
  const { control, register } = useForm();
  const { fields, append, prepend, remove, swap, move, insert } = useFieldArray({
    control, // control props comes from useForm (optional: if you are using FormContext)
    name: "test", // unique name for your Field Array
    // keyName: "id", default to "id", you can change the key name
  });

  return (
    {fields.map((field, index) => (
      <input
        key={field.id} // important to include key with field's id
        name={`test[${index}].value`}
        ref={register()} // register() when there is no validation rules 
        defaultValue={field.value} // make sure to include defaultValue
      />
    ))}
  );
}

Important: useFieldArray is built on top of uncontrolled components. The following notes will help you aware and be mindful of its behaviour during implementation.

  • you can populate the fields by supply defaultValues at useForm hook.

  • make sure you assign id from fields object as your component key.

  • make sure to set defaultValue to fields[index] when you want to set default value, remove or reset with inputs.

  • you can not call actions one after another. Actions need to be triggered per render.

    // ❌ The following is not correct
handleChange={() => {
  if (fields.length === 2) {
    remove(0);
  }
  append({ test: 'test' });
}}

// ✅ The following is correct and second action is triggered after next render
handleChange={() => {
  append({ test: 'test' });
}}

React.useEffect(() => {
  if (fields.length === 2) {
    remove(0);
  }
}, [fields])

  • It's important to apply ref={register()} instead of ref={register} when working with useFieldArray so register will get invoked during map.

  • It doesn't work with custom register at useEffect.

NameTypeDescription
fieldsobject & { id: string }This object is the source of truth to map and render inputs.

Important: because each inputs can be uncontrolled, id is required with mapped components to help React identify which items have changed, are added, or are removed.

eg: {fields.map(d => <input key={d.id} />)}

append(obj: object) => voidAppend input/inputs to the end of your fields
prepend(obj: object) => voidPrepend input/inputs to the start of your fields
insert(index: number, value: object) => voidInsert input/inputs at particular position.
swap(from: number, to: number) => voidSwap input/inputs position.
move(from: number, to: number) => voidMove input/inputs to another position.

Note: difference between move and swap, keep calling move will push input/inputs in a circle, while swap only change two input/inputs' position.

remove(index?: number | number[]) => voidRemove input/inputs at particular position, or remove all when no index is provided.
CodeSandbox TS
import React from "react";
import { useForm, useFieldArray } from "react-hook-form";

function App() {
  const { register, control, handleSubmit, reset, trigger, setError } = useForm({
    // defaultValues: {}; you can populate the fields by this attribute 
  });
  const { fields, append, prepend, remove, swap, move, insert } = useFieldArray({
    control,
    name: "test"
  });
  
  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      <ul>
        {fields.map((item, index) => (
          <li key={item.id}>
            <input
              name={`test[${index}].firstName`}
              ref={register()}
              defaultValue={item.firstName} // make sure to set up defaultValue
            />
            <Controller
              as={<input />}
              name={`test[${index}].lastName`}
              control={control}
              defaultValue={item.lastName} // make sure to set up defaultValue
            />
            <button type="button" onClick={() => remove(index)}>Delete</button>
          </li>
        ))}
      </ul>
      <button
        type="button"
        onClick={() => append({ firstName: "appendBill", lastName: "appendLuo" })}
      >
        append
      </button>
      <input type="submit" />
    </form>
  );
}
CodeSandbox TS
import React from 'react';
import { useForm, useWatch, useFieldArray, Control } from 'react-hook-form';

const ConditionField = ({
  control,
  index,
}: {
  control: Control;
  index: number;
}) => {
  const output = useWatch({
    name: 'data',
    control,
    defaultValue: 'yay! I am watching you :)',
  });

  return (
    <>
      {/* Required shouldUnregister: false */}
      {output[index]?.name === "bill" && (
        <input ref={control.register()} name={`data[${index}].conditional`} />
      )}
      {/* doesn't required shouldUnregister: false */}
      <input
        name={`data[${index}].easyConditional`}
        style={{ display: output[index]?.name === "bill" ? "block" : "none" }}
      />
    </>
  );
};

const UseFieldArrayUnregister: React.FC = () => {
  const { control, handleSubmit, register } = useForm<{
    data: { name: string }[];
  }>({
    defaultValues: {
      data: [{ name: 'test' }, { name: 'test1' }, { name: 'test2' }],
    },
    mode: 'onSubmit',
    shouldUnregister: false,
  });
  const { fields } = useFieldArray<{ name: string }>({
    control,
    name: 'data',
  });
  const onSubmit = (data: any) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {fields.map((data, index) => (
        <>
          <input
            name={`data[${index}].name`}
            defaultValue={data.name}
            ref={register()}
          />
          <ConditionField control={control} index={index} />
        </>
      ))}
      <input type="submit" />
    </form>
  );
};
resolver: (values: any, validationContext?: object) => object

This function allow you to run any external validation methods, such as Joi, Superstruct and etc. In fact, the goal is not only limited Yup as our external (schema) validation library. We would like to support many other validation libraries to work with React Hook Form. You can even write your custom validation logic to validate.

Note: make sure you are returning object which contains values and errors, and their default value should be {}.

Note: returning errors object's key should be relevant to your inputs.

Note: this function will be cached inside the custom hook similar as validationSchema, while validationContext is a mutable object which can be changed on each re-render.

Note: re-validate input will only occur one field at time during user’s interaction, because the lib itself will evaluate the error object to the specific field and trigger re-render accordingly.

import React from "react"
import ReactDOM from "react-dom"
import { useForm } from "react-hook-form"
import * as yup from "yup"

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

export default function App() {
  const { register, handleSubmit, errors } = useForm({
    validationSchema: SignupSchema
  });
  const onSubmit = data => console.log(data);
  console.log(errors);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input name="name" ref={register} />
      <input type="number" name="age" ref={register} />
      <input type="submit" />
    </form>
  );
}import React from 'react';
import { useForm } from 'react-hook-form';
import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from "yup";

type Inputs = {
  name: string;
  age: string;
};

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

const App = () => {
  const { register, handleSubmit } = useForm<Inputs>({
    resolver: yupResolver(schema), // yup, joi and even your own.
  });

  return (
    <form onSubmit={handleSubmit(d => console.log(d))}>
      <input {...register("name")} />
      <input type="number" {...register("age")} />
      <input type="submit" />
    </form>
  );
};
CodeSandbox JS
import { useForm } from "react-hook-form";
import Joi from "joi";

const validationSchema = Joi.object({
  username: Joi.string().required()
});

const resolver = (data: any, validationContext) => {
  const { error, value: values } = validationSchema.validate(data, {
    abortEarly: false
  });

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

export default function App() {
  const { register, handleSubmit, errors } = useForm({
    validationResolver: resolver, // make sure to memoize callback or place it outside the component
    validationContext: { test: "test" }
  });

  return (
    <form onSubmit={handleSubmit(d => console.log(d))}>
      <input type="text" name="username" ref={register} />
      <input type="submit" />
    </form>
  );
}
import * as React from "react";
import { useForm } from "react-hook-form";
import * as Joi from "joi";

type Inputs = {
  username: string;
};

type Context = {
  test: string;
};


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

export default function App() {
  const { register, handleSubmit, errors } = useForm<Inputs, Context>({
    validationResolver: (data, validationContext) => {
      const { error, value: values } = validationSchema.validate(data, { abortEarly: false });

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

  return (
    <div className="App">
      <h1>validationResolver</h1>

      <form onSubmit={handleSubmit(d => console.log(d))}>
        <input type="text" name="username" ref={register} />
        <input type="submit" />
      </form>
    </div>
  );
}

validationSchema: Object

If you would like to centralize your validation rules as an external validation schema, you can use the validationSchema parameter. React Hook Form currently supports Yup for object schema validation.

CodeSandbox TS
import React from "react"
import ReactDOM from "react-dom"
import { useForm } from "react-hook-form"
import * as yup from "yup"

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

export default function App() {
  const { register, handleSubmit, errors } = useForm({
    validationSchema: SignupSchema
  });
  const onSubmit = data => console.log(data);
  console.log(errors);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input name="name" ref={register} />
      <input type="number" name="age" ref={register} />
      <input type="submit" />
    </form>
  );
}
import { Text, View, TextInput, Button, Alert } from "react-native";
import { useForm } from "react-hook-form";

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

export default function App() {
  const { register, setValue, handleSubmit, errors } = useForm({
    validationSchema: schema
  });
  const onSubmit = data => Alert.alert("Form Data", JSON.stringify(data));
  
  useEffect(() => {
    register("firstName");
    register("lastName");
  }, [register]);

  return (
    <View>
      <Text>First name</Text>
      <TextInput onChangeText={text => setValue("firstName", text, true)} />
      {errors.firstName && <Text>This is required.</Text>}

      <Text>Last name</Text>
      <TextInput onChangeText={text => setValue("lastName", text)} />

      <Button onPress={handleSubmit(onSubmit)} />
    </View>
  );
}

Browser built-in validation (V3 only)

The following example demonstrates how you can leverage the browser's validation. You only need to set nativeValidation to true and the rest of the syntax is the same as standard validation.

Note: This feature has been removed in V4 due to low usage, but you can still use it in V3

CodeSandbox TS
import { useForm } from "react-hook-form";

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

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

Advanced Usage

Learn how to build complex and accessible forms

Edit