re:re:actable
Урок 024 минуты чтения

Что такое 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

ПравилоПример
requiredrequired: "Обязательное поле"
minLength / maxLength{ value: 8, message: "..." }
min / maxдля чисел и дат
patternрегулярное выражение
validateсвоя функция: validate: (v) => v !== "admin" || "Имя занято"
valueAsNumber / valueAsDateпривести строку к типу

Для сложных правил удобнее схема Zod через resolver.

Режимы валидации (mode)

modeКогда проверяет
onSubmit (по умолчанию)при отправке, затем при изменениях
onBlurпри потере фокуса
onTouchedпосле первого blur, затем на каждое изменение
onChangeна каждое изменение — больше ререндеров
allblur и 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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам