Что такое react-hook-form: register, handleSubmit и formState
На этой странице
react-hook-form (RHF) — библиотека для форм, построенная на неуправляемых полях и ref: значения хранятся в DOM и внутри библиотеки, а не в state React, поэтому ввод не вызывает ререндер всей формы. useForm возвращает register (подключить поле), handleSubmit (валидация + отправка), formState (ошибки, isSubmitting, isDirty, isValid), а также reset, setValue, watch, setError, setFocus.
Вопрос
Что такое react-hook-form и почему он быстрее управляемых форм? Как работают register, handleSubmit, formState и правила валидации?
Базовая форма
import { useForm, type SubmitHandler } from "react-hook-form";
type SignUp = { name: string; email: string; age: number; agree: boolean };
export function SignUpForm() {
const {
register,
handleSubmit,
reset,
formState: { errors, isSubmitting, isDirty },
} = useForm<SignUp>({
defaultValues: { name: "", email: "", age: 18, agree: false },
mode: "onTouched", // когда валидировать
});
const onSubmit: SubmitHandler<SignUp> = async (data) => {
await api.signUp(data);
reset(); // вернуть к defaultValues
};
return (
<form onSubmit={handleSubmit(onSubmit)} noValidate>
<label htmlFor="name">Имя</label>
<input id="name" {...register("name", { required: "Укажите имя", minLength: { value: 2, message: "Минимум 2 символа" } })} />
{errors.name && <p role="alert">{errors.name.message}</p>}
<label htmlFor="email">Email</label>
<input
id="email"
type="email"
{...register("email", {
required: "Укажите email",
pattern: { value: /^\S+@\S+\.\S+$/, message: "Некорректный email" },
})}
/>
{errors.email && <p role="alert">{errors.email.message}</p>}
<label htmlFor="age">Возраст</label>
<input id="age" type="number" {...register("age", { valueAsNumber: true, min: { value: 18, message: "С 18 лет" } })} />
<label>
<input type="checkbox" {...register("agree", { required: "Нужно согласие" })} /> Принимаю условия
</label>
<button type="submit" disabled={isSubmitting || !isDirty}>
{isSubmitting ? "Отправка…" : "Зарегистрироваться"}
</button>
</form>
);
}register("name") возвращает { name, ref, onChange, onBlur } — их разворачивают в <input>.
Правила валидации register
| Правило | Пример |
|---|---|
required | required: "Обязательное поле" |
minLength / maxLength | { value: 8, message: "..." } |
min / max | для чисел и дат |
pattern | регулярное выражение |
validate | своя функция: validate: (v) => v !== "admin" || "Имя занято" |
valueAsNumber / valueAsDate | привести строку к типу |
Для сложных правил удобнее схема Zod через resolver.
Режимы валидации (mode)
| mode | Когда проверяет |
|---|---|
onSubmit (по умолчанию) | при отправке, затем при изменениях |
onBlur | при потере фокуса |
onTouched | после первого blur, затем на каждое изменение |
onChange | на каждое изменение — больше ререндеров |
all | blur и change |
formState
| Поле | Значение |
|---|---|
errors | ошибки по полям: errors.email?.message |
isSubmitting | выполняется onSubmit (Promise) |
isSubmitSuccessful | последняя отправка прошла без ошибки |
isDirty / dirtyFields | изменены ли поля относительно defaultValues |
touchedFields | поля, которые теряли фокус |
isValid | форма проходит валидацию |
formState — прокси: RHF ререндерит компонент только при изменении тех полей, которые вы прочитали.
Полезные методы
const { watch, setValue, setFocus, reset, getValues } = useForm<SignUp>();
const email = watch("email"); // подписка на значение (вызывает ререндер)
setValue("name", "Анна", { shouldValidate: true, shouldDirty: true });
setFocus("email");
reset(userFromServer); // заполнить форму данными после загрузкиДля подписки без ререндера всей формы используют useWatch({ control, name }) в отдельном дочернем компоненте.
Что важно помнить
defaultValuesзадавайте всегда: от них считаетсяisDirty, и поля не будут переключаться из неуправляемых в управляемые.- Данные, загруженные после монтирования, подставляют через
reset(data)или опциюvalues. - Атрибут
noValidateотключает встроенные подсказки браузера, если ошибки показывает RHF. watchна уровне формы ререндерит всю форму — для одного поля лучшеuseWatchв маленьком компоненте.handleSubmitсам вызываетpreventDefaultи не вызоветonSubmit, если валидация не прошла.
Мини-шпаргалка
useForm({ defaultValues, mode, resolver }) → register(name, rules), handleSubmit(onSubmit), formState: { errors, isSubmitting, isDirty, isValid }, reset, setValue, setError, setFocus, watch / useWatch. Неуправляемые поля → мало ререндеров.
Документация
React Hook Form: Get Started, React Hook Form: useForm, React Hook Form: register, React Hook Form: formState.