register

</> `register:` UseFormRegister

This method allows you to register an input or select element and apply validation rules in React Hook Form. Validation rules are all based on the HTML standard and also allow for custom validation methods.

Props

Name	Type	Description
`name`	string	Input's name.
`options`	RegisterOptions	Input's behavior.

Return

Name	Type	Description
`ref`	React.Ref	React element ref used to connect hook form to the input.
`name`	string	Input's name being registered.
`onChange`	ChangeHandler	`onChange` prop to subscribe to the input change event.
`onBlur`	ChangeHandler	`onBlur` prop to subscribe to the input blur event.
`min`	string \| number	Since v7.21.0 Present only when `progressive` is `true`; reflects the `min` rule if one was set (otherwise `undefined`).
`max`	string \| number	Since v7.21.0 Present only when `progressive` is `true`; reflects the `max` rule if one was set (otherwise `undefined`).
`maxLength`	number	Since v7.21.0 Present only when `progressive` is `true`; reflects the `maxLength` rule if one was set (otherwise `undefined`).
`minLength`	number	Since v7.21.0 Present only when `progressive` is `true`; reflects the `minLength` rule if one was set (otherwise `undefined`).
`pattern`	string	Since v7.21.0 Present only when `progressive` is `true`; reflects the `pattern` rule if one was set (otherwise `undefined`).
`required`	boolean	Since v7.21.0 Present only when `progressive` is `true`; reflects the `required` rule if one was set (otherwise `false`).
`disabled`	boolean	Since v7.21.0 optional. Present when the `disabled` option is set.

NOTE

This is how submitted values will look like:

Input Name	Submit Result
register("firstName")	`{ firstName: value }`
register("name.firstName")	`{ name: { firstName: value } }`
register("name.firstName.0")	`{ name: { firstName: [ value ] } }`

Options

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

NOTE

These are validation rules, not native HTML attributes. They run based on the form's mode and don't block typing. To also forward required, min, max, minLength, maxLength, and pattern as native attributes on the input, set progressive to true on useForm.

Name	Description
`required` boolean	Indicates that the input must have a value before the form can be submitted. Note: This config aligns with web constrained API for required input validation, for object or array input types, use the validate function instead.
`maxLength` number	The maximum length of the value to accept for this input.
`minLength` number	The minimum length of the value to accept for this input.
`max` number	The maximum value to accept for this input.
`min` number	The minimum value to accept for this input.
`pattern` RegExp	The regex pattern for the input. Note: `RegExp` with the `/g` flag keeps track of the last index where a match occurred.
`validate` Function \| `Record<string, Function>`	Validate function will be executed on its own without depending on other validation rules included in the required attribute. The function receives the field value (and, Since v7.42.0 optionally the full form values as a second argument) and must return one of: `true` or `undefined` — field is valid (both are treated identically; explicit `return true` is conventional but not required) A `string` — field is invalid; the string is used as the error message `false` — field is invalid with no custom message (a generic error is used) Pass an object of named functions to run multiple independent validations, each with its own error message. Note: for object or array input data, it's recommended to use the validate function for validation as the other rules mostly apply to strings, arrays of strings, numbers, and booleans.
`valueAsNumber` boolean	Returns `Number` normally. If something goes wrong `NaN` will be returned. `valueAs` process is happening before validation. Only applies to number input, but without any data manipulation. Does not transform `defaultValue` or `defaultValues`.
`valueAsDate` boolean	Returns `Date` normally. If something goes wrong `Invalid Date` will be returned. `valueAs` process is happening before validation. Only applies to input. Does not transform `defaultValue` or `defaultValues`.
`setValueAs` <T>(value: any) => T	Return input value by running through the function. `valueAs` process is happening before validation. Also, `setValueAs` is ignored if either `valueAsNumber` or `valueAsDate` are true. Only applies to text input. Does not transform `defaultValue` or `defaultValues`.
`disabled` boolean = false	Since v7.13.0 Set `disabled` to `true` will lead input value to be `undefined` and input control to be disabled. `disabled` prop will also omit built-in validation rules. For schema validation, you can leverage the `undefined` value returned from input or context object.
`onChange` (e: SyntheticEvent) => void	Since v7.16.0 `onChange` function event to be invoked in the change event.
`onBlur` (e: SyntheticEvent) => void	Since v7.16.0 `onBlur` function event to be invoked in the blur event.
`value` unknown	Since v7.8.0 Set up `value` for the registered input. This prop should be utilised inside `useEffect` or invoked once, each re-run will update or overwrite the input value which you have supplied.
`shouldUnregister` boolean	Input will be unregistered after unmount and `defaultValues` will be removed as well. Note: this prop should be avoided when using with `useFieldArray` as unregister function gets called after input unmount/remount and reorder.
`deps` string \| string[]	Since v7.14.0 When this field's own validation runs (e.g. via its registered `onChange`/`onBlur`), the fields listed in `deps` will also be re-validated. Calling `trigger()` manually does not honor `deps`.

Name	Description
`required` string \| { value: boolean, message: string }	Indicates that the input must have a value before the form can be submitted. Note: This config aligns with web constrained API for required input validation, for object or array input types, use the validate function instead.
`maxLength` { value: number, message: string }	The maximum length of the value to accept for this input.
`minLength` { value: number, message: string }	The minimum length of the value to accept for this input.
`max` { value: number, message: string }	The maximum value to accept for this input.
`min` { value: number, message: string }	The minimum value to accept for this input.
`pattern` { value: RegExp, message: string }	The regex pattern for the input. Note: `RegExp` with the `/g` flag keeps track of the last index where a match occurred.
`validate` Function \| `Record<string, Function>`	Validate function will be executed on its own without depending on other validation rules included in the required attribute. The function receives the field value (and, Since v7.42.0 optionally the full form values as a second argument) and must return one of: `true` or `undefined` — field is valid (both are treated identically; explicit `return true` is conventional but not required) A `string` — field is invalid; the string is used as the error message `false` — field is invalid with no custom message (a generic error is used) Pass an object of named functions to run multiple independent validations, each with its own error message. Note: for object or array input data, it's recommended to use the validate function for validation as the other rules mostly apply to strings, arrays of strings, numbers, and booleans.
`valueAsNumber` boolean	Returns `Number` normally. If something goes wrong `NaN` will be returned. `valueAs` process is happening before validation. Only applies to number input, but without any data manipulation. Does not transform `defaultValue` or `defaultValues`.
`valueAsDate` boolean	Returns `Date` normally. If something goes wrong `Invalid Date` will be returned. `valueAs` process is happening before validation. Only applies to input. Does not transform `defaultValue` or `defaultValues`.
`setValueAs` <T>(value: any) => T	Return input value by running through the function. `valueAs` process is happening before validation. Also, `setValueAs` is ignored if either `valueAsNumber` or `valueAsDate` are true. Only applies to text input. Does not transform `defaultValue` or `defaultValues`.
`disabled` boolean = false	Since v7.13.0 Set `disabled` to `true` will lead input value to be `undefined` and input control to be disabled. `disabled` prop will also omit built-in validation rules. For schema validation, you can leverage the `undefined` value returned from input or context object.
`onChange` (e: SyntheticEvent) => void	Since v7.16.0 `onChange` function event to be invoked in the change event.
`onBlur` (e: SyntheticEvent) => void	Since v7.16.0 `onBlur` function event to be invoked in the blur event.
`value` unknown	Since v7.8.0 Set up `value` for the registered input. This prop should be utilised inside `useEffect` or invoked once, each re-run will update or overwrite the input value which you have supplied.
`shouldUnregister` boolean	Input will be unregistered after unmount and `defaultValues` will be removed as well. Note: this prop should be avoided when using with `useFieldArray` as unregister function gets called after input unmount/remount and reorder.
`deps` string \| string[]	Since v7.14.0 When this field's own validation runs (e.g. via its registered `onChange`/`onBlur`), the fields listed in `deps` will also be re-validated. Calling `trigger()` manually does not honor `deps`.

RULES

Name is required and must be unique (except for native radio and checkbox inputs).
Names must not start with a number or use numbers as standalone keys, and should avoid special characters. For TypeScript consistency, only dot syntax is supported—bracket syntax ([]) will not work for array form values.
```
register("test.0.firstName") // ✅
register("test[0].firstName") // ❌
```
Disabled inputs return undefined as their form value. If you need to prevent user edits while preserving the value, use readOnly or disable the entire fieldset. Here is an example.
Changing an input’s name on each render causes it to be re-registered as a new field. To ensure consistent behavior, keep input names stable across renders.
Input values and references are not automatically removed on unmount. Use unregister to explicitly remove them when needed.
Calling register again on the same name merges the new options into the existing ones — it does not replace them — so individual register options cannot be removed using undefined or {}. You can update individual attributes instead.
```
register('test', { required: true });
register('test', {}); // ❌
register('test', undefined); // ❌
register('test', { required: false });  // ✅
```
There are certain keywords that should be avoided to prevent conflicts with type checks. They are ref and _f.

Examples

Register input or select

CodeSandbox ^JS

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

export default function App() {
  const { register, handleSubmit } = useForm({
    defaultValues: {
      firstName: "",
      lastName: "",
      category: "",
      checkbox: [],
      radio: "",
    },
  })

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input
        {...register("firstName", { required: true })}
        placeholder="First name"
      />

      <input
        {...register("lastName", { minLength: 2 })}
        placeholder="Last name"
      />

      <select {...register("category")}>
        <option value="">Select...</option>
        <option value="A">Category A</option>
        <option value="B">Category B</option>
      </select>

      <input {...register("checkbox")} type="checkbox" value="A" />
      <input {...register("checkbox")} type="checkbox" value="B" />
      <input {...register("checkbox")} type="checkbox" value="C" />

      <input {...register("radio")} type="radio" value="A" />
      <input {...register("radio")} type="radio" value="B" />
      <input {...register("radio")} type="radio" value="C" />

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

Custom async validation

import { useForm } from "react-hook-form"
import { checkProduct } from "./service"

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

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <select
        {...register("category", {
          required: true,
        })}
      >
        <option value="">Select...</option>
        <option value="A">Category A</option>
        <option value="B">Category B</option>
      </select>

      <input
        type="text"
        {...register("product", {
          validate: {
            checkAvailability: async (product, { category }) => {
              if (!category) return "Choose a category"
              if (!product) return "Specify your product"
              const isInStock = await checkProduct(category, product)
              return isInStock || "There is no such product"
            },
          },
        })}
      />

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

Video

Tips

Destructuring assignment

const { onChange, onBlur, name, ref } = register('firstName');
// Include a type check against the field path with the name you have supplied.

<input
  onChange={onChange} // assign onChange event
  onBlur={onBlur} // assign onBlur event
  name={name} // assign name prop
  ref={ref} // assign ref prop
/>
// same as above
<input {...register('firstName')} />

Custom Register

You can also register inputs with useEffect and treat them as virtual inputs. For controlled components, we provide a custom hook useController and Controller component to take care of this process for you.

If you choose to manually register fields, you will need to update the input value with setValue.

register("firstName", { required: true, minLength: 8 })
;<TextInput onTextChange={(value) => setValue("firstName", value)} />

How to work with `innerRef`, `inputRef`?

When the custom input component doesn't expose the ref correctly, you can get it working via the following method.

// not working, because ref is not assigned
<TextInput {...register('test')} />

const firstName = register('firstName', { required: true })
<TextInput
  name={firstName.name}
  onChange={firstName.onChange}
  onBlur={firstName.onBlur}
  inputRef={firstName.ref} // you can achieve the same for different ref names such as innerRef
/>

Thank you for your support

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

</> register: UseFormRegister