Skip to content

register

Register uncontrolled/controlled inputs

register: (name: string, RegisterOptions?) => ({ onChange, onBlur, name, ref })

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

By invoking the register function and supplying an input's name, you will receive the following methods:

Props

NameTypeDescription
onChangeChangeHandler

onChange prop to subscribe the input change event.

onBlurChangeHandler

onBlur prop to subscribe the input blur event.

namestring

Input's name being registered.

Input NameSubmit Result
register("firstName"){firstName: 'value'}
register("name.firstName"){name: { firstName: 'value' }}
register("name.firstName.0"){name: { firstName: [ 'value' ] }}

Return

Tip:: What's happened to the input after invoke register API:

const { onChange, onBlur, name, ref } = register('firstName'); 
// include type check against 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')} />

Options

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

Select Options
NameDescriptionCode Examples
ref
React.Ref		React element ref
<input {...register("test")} />
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.

Note: This config aligns with web constrained API for required input validation, for object or array type of input use validate function instead.

<input
  {...register("test", {
    required: true
  })}
/>
maxLength
number		The maximum length of the value to accept for this input.
<input
  {...register("test", {
      maxLength: 2
  })}
/>
minLength
number		The minimum length of the value to accept for this input.
<input
  {...register("test", {
    minLength: 1
  })}
/>
max
number		The maximum value to accept for this input.
<input
  type="number"
  {...register('test', {
    max: 3
  })}
/>
min
number		The minimum value to accept for this input.
<input
  type="number"
  {...register("test", {
    min: 3
  })}
/>
pattern
RegExp

The regex pattern for the input.

Note: A RegExp object with the /g flag keeps track of the lastIndex where a match occurred.

<input
  {...register("test", {
    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. This function will be executed on its own without depending on other validation rules included in the required attribute.

Note: for object or array input data, it's recommended to use the validate function for validation as the other rules mostly apply to string, string[], number and boolean data types.

<input
  {...register("test", {
    validate: (value, formValues) => value === '1'
  })}
/>
// object of callback functions
<input
  {...register("test1", {
    validate: {
      positive: v => parseInt(v) > 0,
      lessThanTen: v => parseInt(v) < 10,
      validateNumber: (_, values) =>
        !!(values.number1 + values.number2), 
      checkUrl: async () => await fetch(),
    }
  })}
/>
valueAsNumber:
boolean

Returns a Number normally. If something goes wrong NaN will be returned.

  • valueAs process is happening before validation.

  • Only applicable and support to <input type="number" />, but we still cast to number type without trim or any other data manipulation.

  • Does not transform defaultValue or defaultValues.
<input
  type="number"
  {...register("test", {
    valueAsNumber: true,
  })}
/>
valueAsDate:
boolean

Returns a Date object 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.
<input
  type="date"
  {...register("test", {
    valueAsDate: true,
  })}
/>
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.
<input
  type="number"
  {...register("test", {
    setValueAs: v => parseInt(v),
  })}
/>
disabled
boolean = false

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.

<input
  {...register("test", {
    disabled: true
  })}
/>
onChange
(e: SyntheticEvent) => void

onChange function event to be invoked in the change event.

register('firstName', {
  onChange: (e) => console.log(e)
})
onBlur
(e: SyntheticEvent) => void

onBlur function event to be invoked in the blur event.

register('firstName', {
  onBlur: (e) => console.log(e)
})
value
unknown

Set up value for the registered input. This prop should be utilised inside useEffect or invoke once, each re-run will update or overwrite the input value which you have supplied.

register('firstName', { value: 'bill' })
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.

<input
  {...register("test", {
    shouldUnregister: true,
  })}
/>
deps:
string | string[]

Validation will be triggered for the dependent inputs,it only limited to register api not trigger.

<input
  {...register("test", {
    deps: ['inputA', 'inputB'],
  })}
/>

Rules

  • name is required and unique (except native radio and checkbox). Input name supports both dot and bracket syntax, which allows you to easily create nested form fields.

  • name can neither start with a number nor use number as key name. Please avoid special characters as well.

  • we are using dot syntax only for typescript usage consistency, so bracket [] will not work for array form value.

    register('test.0.firstName'); // ✅
    register('test[0]firstName'); // ❌

  • disabled input will result in an undefined form value. If you want to prevent users from updating the input, you can use readOnly or disable the entire <fieldset />. Here is an example.

  • To produce an array of fields, input names should be followed by a dot and number. For example: test.0.data

  • Changing the name on each render will result in new inputs being registered. It's recommended to keep static names for each registered input.

  • Input value and reference will no longer gets removed based on unmount. You can invoke unregister to remove that value and reference.

  • Individual register option can't be removed by undefined or {}. You can update individual attribute instead.

    register('test', { required: true });
    register('test', {}); // ❌
    register('test', undefined); // ❌
    register('test', { required: false });  // ✅

  • There are certain keyword which need to avoid before conflicting with type check. They are ref, _f

Examples

CodeSandbox JS
import * as React from "react";
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>
  );
}

Video

The following video explain register API in detail.

Tips

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 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, min: 8 });


<TextInput onTextChange={(value) => setValue('lastChange', value))} />

How to work with innerRef, inputRef?

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

// 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 name such as innerRef
/>


// correct way to forward input's ref
const Select = React.forwardRef(({ onChange, onBlur, name, label }, ref) => (
  <select name={name} ref={ref} onChange={onChange} onBlur={onBlur}>
    <option value="20">20</option>
    <option value="30">30</option>
  </select>
));
React Hook Form 中文网 - 粤ICP备13048890号