Skip to content

Migration Guide

V5 to V6

Hi there,

Here are the breaking changes you would need to adjust. We sincerely hope those changes aren't creating too much trouble for your codebase. If you are wondering some of the rationals behind, you can take a look at this pull request for more details.

❤️ React hook Form Team

useForm:

We are removing validation prefix for all the config.

const { register } = useForm({
  - validationResolver: undefined,
  + resolver: undefined,

  - validationContext: undefined,
  + context: undefined,

  - validateCriteriaMode: "firstError",
  + criteriaMode: "firstError",
  
  - submitFocusError: true,
  + shouldFocusError: true,
})

validationSchema:

validationSchema has been replace with standard resolver, and you can use Yup, Joi and Superstruct at the moment. We have an official resolver library to support more schema validation in the future.

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

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

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>
  );
};

Controller:

We made Controller's API much simpler, and the following props have been removed and replaced with render props.

  • onChange

  • onBlur

  • onChangeName

  • onBlueName

  • valueName

- <Controller as={Input}
-   name="test"
-   onChange={([_, value]) => value}
-   onChangeName="onTextChange"
-   onBlur={([_, value]) => value}
-   onBlurName="onTextChange"
-   valueName="textValue"
- />

+ <Controller name="test"
+   render={({ onChange, onBlur, value }) => {
+     return <Input
+       valueName={value}
+       onTextChange={(val) => onChange(value)}
+       onTextBlur={(val) => onBlur(value)}
+     />
+   }}
+ />

watch:

watch will no longer return flat form values, instead it will return nested object data by default.

- watch({ nest: true });
+ watch();

getValues:

getValues will no longer return flat form values, instead it will return nested object data by default.

- getValues({ nest: true });
+ getValues();

triggerValidation:

method's name is renamed to trigger.

- triggerValidation();
+ trigger();

FormContext:

component's name is renamed to FormProvider, and now you can use FormContext.Consumer as well.

- <FormContext {...methods}>
+ <FormProvider {...methods}>

Dirty:

Changing name from dirty to isDirty.

- const { dirty } = formState;
+ const { isDirty } = formState;

dirtyFields:

Changing data type from Set to Object.

- const { dirtyFields } = formState;
- dirtyFields.has('test');
+ const { dirtyFields } = formState;
+ dirtyFields.test;

ErrorMessage:

Move away from the core library.

npm install @hookform/error-message

clearErrors:

Rename function to clearErrors.

- clearError('test')
+ clearErrors('test')

setError:

Syntax update and no longer support multiple errors.

- setError('test', 'required', 'message')
+ setError('test', { type: 'required', message: 'message' })

- setError([ { name: 'test1', type: "max", }, { name: 'test', type: "min", } ])
+ [
+   { name: 'test1', type: "max" },
+   { name: 'test', type: "min" }
+ ].forEach(({ name, type }) => setError(name, { type }))

setValue:

Syntax update and no longer dirty field by default and stop supporting multiple errors.

- setValue('test', 'data')
+ setValue('test', 'data', { shouldDirty: true })

- setValue([ { test: "1", }, { test1: "2", } ])
+ [ { name: 'test', value: 'data' } ].forEach(({ name, value }) => setValue(name, value))