useForm (original) (raw)

</> useForm: UseFormProps

useForm is a custom hook for managing forms with ease. It takes one object as optional argument. The following example demonstrates all of its properties along with their default values.

Generic props:

Schema validation props:

Props

mode: onChange | onBlur | onSubmit | onTouched | all = 'onSubmit'

This option allows you to configure the validation strategy before a user submits the form. The validation occurs during the onSubmit event, which is triggered by invoking the handleSubmit function.

reValidateMode: onChange | onBlur | onSubmit = 'onChange'

This option allows you to configure validation strategy when inputs with errors get re-validated after a user submits the form (onSubmit event and handleSubmit function executed). By default, re-validation occurs during the input change event.

defaultValues: FieldValues | () => Promise<FieldValues>

The defaultValues prop populates the entire form with default values. It supports both synchronous and asynchronous assignment of default values. While you can set an input's default value using defaultValue or defaultChecked (as detailed in the official React documentation), it is recommended to use defaultValues for the entire form.

useForm({

defaultValues: {

firstName: '',

lastName: ''

}

})

useForm({

defaultValues: async () => fetch('/api-endpoint');

})

RULES

• You should avoid providing undefined as a default value, as it conflicts with the default state of a controlled component.
• defaultValues are cached. To reset them, use the reset API.
• defaultValues will be included in the submission result by default.
• It's recommended to avoid using custom objects containing prototype methods, such as Moment or Luxon, as defaultValues.
• There are other options for including form data:
  <input {...register("hidden", { value: "data" })} type="hidden" />
  const onSubmit = (data) => {
  const output = {
  ...data,
  others: "others",
  }
  }

values: FieldValues

The values prop will react to changes and update the form values, which is useful when your form needs to be updated by external state or server data. The values prop will overwrite the defaultValues prop, unless resetOptions: { keepDefaultValues: true } is also set for useForm.

function App({ values }) {

useForm({

values, 

})

}

function App() {

const values = useFetch("/api")

useForm({

defaultValues: {

  firstName: "",

  lastName: "",

},

values, 

})

}

errors: FieldErrors

The errors props will react to changes and update the server errors state, which is useful when your form needs to be updated by external server returned errors.

function App() {

const { errors, data } = useFetch("/api")

useForm({

errors, 

})

}

resetOptions: KeepStateOptions

This property is related to value update behaviors. When values or defaultValues are updated, the reset API is invoked internally. It's important to specify the desired behavior after values or defaultValues are asynchronously updated. The configuration option itself is a reference to the reset method's options.

useForm({ values })

useForm({ defaultValues: async () => await fetch() })

useForm({

values,

resetOptions: {

keepDirtyValues: true, 

keepErrors: true, 

},

})

context: object

criteriaMode: firstError | all

shouldFocusError: boolean = true

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

NOTE

• Only registered fields with a ref will work. Custom registered inputs do not apply. For example: register('test') // doesn't work
• The focus order is based on the register order.

delayError: number

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 configuration that overrides child-level configurations. To have individual behavior, set the configuration at the component or hook level, not at useForm.
• By default, shouldUnregister: false means unmounted fields are not validated by built-in validation.
• By setting shouldUnregister to true at useForm level, defaultValues will not be merged against submission result.
• Setting shouldUnregister: true makes your form behave more closely to native forms.
  • Form values are stored within the inputs themselves.
  • Unmounting an input removes its value.
  • Hidden inputs should use the hidden attribute for storing hidden data.
  • Only registered inputs are included as submission data.
  • Unmounted inputs must be notified at either useForm or useWatch's useEffect for the hook form to verify that the input is unmounted from the DOM.
    const NotWork = () => {
    const [show, setShow] = React.useState(false)
    return show && <input {...register("test")} />
    }
    const Work = ({ control }) => {
    const { show } = useWatch({ control })
    return show && <input {...register("test1")} />
    }
    const App = () => {
    const [show, setShow] = React.useState(false)
    const { control } = useForm({ shouldUnregister: true })
    return (
    {show && }
    ) }

shouldUseNativeValidation: boolean = false

This config will enable browser native validation. It will also enable CSS selectors :valid and:invalid making styling inputs easier. You can still use these selectors even when client-side validation is disabled.

• Only works with onSubmit and onChange modes, as the reportValidity execution will focus the error input.
• Each registered field's validation message is required to be string to display them natively.
• This feature only works with the register API and useController/Controller that are connected with actual DOM references.

Examples:

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.",

    })} 

  />

  <input type="submit" />

</form>

)

}

disabled: boolean = false

This config allows you to disable the entire form and all associated inputs when set to true.
This can be useful for preventing user interaction during asynchronous tasks or other situations where inputs should be temporarily unresponsive.

Examples:

import { useForm, Controller } from "react-hook-form"

const App = () => {

const [disabled, setDisabled] = useState(false)

const { register, handleSubmit, control } = useForm({

disabled,

})

return (

<form

  onSubmit={handleSubmit(async () => {

    setDisabled(true)

    await sleep(100)

    setDisabled(false)

  })}

>

  <input

    type={"checkbox"}

    {...register("checkbox")}

    data-testid={"checkbox"}

  />

  <select {...register("select")} data-testid={"select"} />

  <Controller

    control={control}

    render={({ field }) => <input disabled={field.disabled} />}

    name="test"

  />

  <button type="submit">Submit</button>

</form>

)

}

resolver: Resolver

This function allows you to use any external validation library such as Yup, Zod, Joi, Vest, Ajv 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.

npm install @hookform/resolvers

Props

RULES

• Schema validation focuses on field-level error reporting. Parent-level error checking is limited to the direct parent level, which 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 can not be used with the built-in validators (e.g.: required, min, etc.)
• When building a custom resolver:
  • Make sure that you return an object with both values and errors properties. 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"

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({

resolver: yupResolver(schema), 

})

return (

<form onSubmit={handleSubmit((d) => console.log(d))}>

  <input {...register("name")} />

  <input type="number" {...register("age")} />

  <input type="submit" />

</form>

)

}

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(),

})

type Schema = z.infer

const App = () => {

const { register, handleSubmit } = useForm({

resolver: zodResolver(schema),

})

const onSubmit = (data: Schema) => {

console.log(data)

}

return (

<form onSubmit={handleSubmit(onSubmit)}>

  <input {...register("name")} />

  <input {...register("age", { valueAsNumber: true })} 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";

interface IFormInput {

name: string;

age: number;

}

const schema = Joi.object({

name: Joi.string().required(),

age: Joi.number().required()

});

const App = () => {

const { register, handleSubmit, formState: { errors } } = useForm({

resolver: joiResolver(schema)

});

const onSubmit = (data: IFormInput) => {

console.log(data);

};

return (

<form onSubmit={handleSubmit(onSubmit)}>

  <input {...register("name"} />

  <input type="number" {...register("age"} />

  <input type="submit" />

</form>

);

}

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

import { ajvResolver } from "@hookform/resolvers/ajv"

const schema = {

type: "object",

properties: {

username: {

  type: "string",

  minLength: 1,

  errorMessage: { minLength: "username field is required" },

},

password: {

  type: "string",

  minLength: 1,

  errorMessage: { minLength: "password field is required" },

},

},

required: ["username", "password"],

additionalProperties: false,

}

const App = () => {

const {

register,

handleSubmit,

formState: { errors },

} = useForm({

resolver: ajvResolver(schema),

})

return (

<form onSubmit={handleSubmit((data) => console.log(data))}>

  <input {...register("username")} />

  {errors.username && <p>{errors.username.message}</p>}

  <input {...register("password")} />

  {errors.password && <p>{errors.password.message}</p>}

  <button type="submit">submit</button>

</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]/)

})

})

const 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"

interface IFormInputs {

username: string

}

const validationSchema = Joi.object({

username: Joi.string().alphanum().min(3).max(30).required(),

})

const App = () => {

const {

register,

handleSubmit,

formState: { errors },

} = useForm({

resolver: async (data) => {

  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,

          }

        }, {})

      : {},

  }

},

})

const onSubmit = (data: IFormInputs) => 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>

)

}

Need more? See Resolver Documentation

TIP

You can debug your schema via the following code snippet:

resolver: async (data, context, options) => {

console.log("formData", data)

console.log(

"validation result",

await anyResolver(schema)(data, context, options)

)

return anyResolver(schema)(data, context, options)

}

useForm return and useEffect dependencies

In a future major release, useForm return will be memoized to optimize performance and reflect changes in formState. As a result, adding the entire return value of useForm to a useEffect dependency list may lead to infinite loops.

WARNING

The following code is likely to create this situation:

const methods = useForm()

useEffect(() => {

methods.reset({ ... })

}, [methods])

Passing only the relevant methods, as showed below, should avoid this kind of issue:

const methods = useForm()

useEffect(() => {

methods.reset({ ... })

}, [methods.reset])

TIP

The recommended way is to pass destructured methods to the dependencies of an useEffect

const { reset } = useForm()

useEffect(() => {

reset({ ... })

}, [reset])

More info can be found on this issue

Return

The following list contains reference to useForm return props.

• register
• unregister
• formState
• watch
• handleSubmit
• reset
• resetField
• setError
• clearErrors
• setValue
• setFocus
• getValues
• getFieldState
• trigger
• control
• Form

Thank you for your support

If you find React Hook Form to be useful in your project, please consider to star and support it.