useFormStatus - отслеживание статуса отправки формы

Введение

Работа с формами — одна из самых частых задач в разработке веб-приложений. При отправке формы пользователь должен видеть, что запрос обрабатывается: кнопка блокируется, появляется спиннер, поля становятся неактивными. До React 19 для этого приходилось вручную управлять состоянием загрузки и пробрасывать его через пропсы.

Хук useFormStatus решает эту проблему элегантно: он позволяет любому дочернему компоненту формы получить информацию о текущем статусе её отправки — без лишних пропсов и передачи состояния вручную.

Если вы хотите глубже изучить React и современные подходы к разработке форм, рекомендую курс по React на PurpleSchool.

Что такое useFormStatus

useFormStatus — это хук из пакета react-dom, появившийся в React 19. Он предоставляет информацию о состоянии ближайшей родительской формы (<form>). Хук возвращает объект с полями, описывающими текущий статус отправки.

Ключевая особенность: хук работает только внутри компонента, который является дочерним по отношению к элементу <form>. Он не работает в самом компоненте формы — только в его потомках.

Синтаксис

import { useFormStatus } from 'react-dom';

function SubmitButton() {
  const { pending, data, method, action } = useFormStatus();
  // ...
}

Возвращаемые значения

Хук возвращает объект со следующими полями:

Самое используемое поле — pending. Именно оно позволяет реагировать на момент ожидания ответа сервера.

Зачем нужен useFormStatus

Рассмотрим типичную проблему: нужно заблокировать кнопку отправки, пока форма обрабатывается, и показать текст «Отправка...».

Без useFormStatus (классический подход)

import React, { useState } from 'react';

function ContactForm() {
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setIsSubmitting(true);
    try {
      await sendContactForm(new FormData(e.target as HTMLFormElement));
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" placeholder="Email" />
      <textarea name="message" placeholder="Сообщение" />
      {/* Приходится передавать isSubmitting в кнопку */}
      <SubmitButton isSubmitting={isSubmitting} />
    </form>
  );
}

function SubmitButton({ isSubmitting }: { isSubmitting: boolean }) {
  return (
    <button type="submit" disabled={isSubmitting}>
      {isSubmitting ? 'Отправка...' : 'Отправить'}
    </button>
  );
}

Здесь isSubmitting нужно явно передавать через пропсы. При глубокой вложенности компонентов это превращается в «пробрасывание пропсов» (prop drilling).

С useFormStatus (современный подход)

import { useFormStatus } from 'react-dom';

// Компонент кнопки сам знает о статусе формы
function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Отправка...' : 'Отправить'}
    </button>
  );
}

function ContactForm() {
  async function handleSubmit(formData: FormData) {
    await sendContactForm(formData);
  }

  return (
    <form action={handleSubmit}>
      <input name="email" type="email" placeholder="Email" />
      <textarea name="message" placeholder="Сообщение" />
      {/* Кнопке не нужны дополнительные пропсы */}
      <SubmitButton />
    </form>
  );
}

Кнопка сама определяет свой статус — код стал чище, а компонент переиспользуемым.

Основные примеры использования

Пример 1: Кнопка отправки с индикатором загрузки

Самый распространённый кейс — блокировка кнопки и смена её текста.

import { useFormStatus } from 'react-dom';

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className={`btn ${pending ? 'btn-loading' : 'btn-primary'}`}
    >
      {pending ? (
        <>
          <span className="spinner" />
          Сохраняем...
        </>
      ) : (
        'Сохранить'
      )}
    </button>
  );
}

// Использование в форме
function ProfileForm() {
  async function updateProfile(formData: FormData) {
    'use server';
    await saveProfileToDatabase({
      name: formData.get('name') as string,
      bio: formData.get('bio') as string,
    });
  }

  return (
    <form action={updateProfile}>
      <input name="name" placeholder="Имя" defaultValue="Иван Петров" />
      <textarea name="bio" placeholder="О себе" />
      <SubmitButton />
    </form>
  );
}

Пример 2: Блокировка всей формы во время отправки

Иногда нужно заблокировать не только кнопку, но и все поля формы.

import { useFormStatus } from 'react-dom';

function FormField({
  name,
  label,
  type = 'text',
}: {
  name: string;
  label: string;
  type?: string;
}) {
  const { pending } = useFormStatus();

  return (
    <div className="form-group">
      <label htmlFor={name}>{label}</label>
      <input
        id={name}
        name={name}
        type={type}
        disabled={pending}
        className={pending ? 'input-disabled' : ''}
      />
    </div>
  );
}

function RegisterForm() {
  async function registerUser(formData: FormData) {
    'use server';
    await createUserAccount({
      email: formData.get('email') as string,
      password: formData.get('password') as string,
      name: formData.get('name') as string,
    });
  }

  return (
    <form action={registerUser}>
      <FormField name="name" label="Имя" />
      <FormField name="email" label="Email" type="email" />
      <FormField name="password" label="Пароль" type="password" />
      <SubmitButton />
    </form>
  );
}

Пример 3: Отображение прогресса с данными формы

Поле data позволяет показать, какие данные отправляются прямо сейчас.

import { useFormStatus } from 'react-dom';

function FormStatus() {
  const { pending, data } = useFormStatus();

  if (!pending || !data) return null;

  const email = data.get('email');

  return (
    <div className="form-status">
      <span className="spinner" />
      <p>
        Отправляем на <strong>{email as string}</strong>...
      </p>
    </div>
  );
}

function NewsletterForm() {
  async function subscribe(formData: FormData) {
    'use server';
    await addToNewsletter(formData.get('email') as string);
  }

  return (
    <form action={subscribe}>
      <input name="email" type="email" placeholder="Ваш email" />
      <FormStatus />
      <button type="submit">Подписаться</button>
    </form>
  );
}

Интеграция с Next.js Server Actions

useFormStatus особенно полезен в Next.js App Router, где формы часто работают с Server Actions.

Базовый пример с Server Action

// app/actions.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  // Имитируем задержку сервера
  await new Promise((resolve) => setTimeout(resolve, 1500));

  await db.post.create({ data: { title, content } });
  revalidatePath('/posts');
}

// app/posts/new/page.tsx
import { createPost } from '../actions';
import { SubmitButton } from '@/components/SubmitButton';

export default function NewPostPage() {
  return (
    <div className="container">
      <h1>Новая запись</h1>
      <form action={createPost}>
        <div>
          <label htmlFor="title">Заголовок</label>
          <input id="title" name="title" required />
        </div>
        <div>
          <label htmlFor="content">Содержание</label>
          <textarea id="content" name="content" rows={10} required />
        </div>
        <SubmitButton />
      </form>
    </div>
  );
}

// components/SubmitButton.tsx
'use client';

import { useFormStatus } from 'react-dom';

export function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Публикуем...' : 'Опубликовать'}
    </button>
  );
}

Обратите внимание: компонент с useFormStatus должен быть клиентским ('use client'), потому что useFormStatus — это клиентский хук. Но форма и Server Action могут оставаться серверными.

Паттерн: переиспользуемый компонент кнопки

В реальных проектах удобно создать универсальную кнопку отправки.

// components/SubmitButton.tsx
'use client';

import { useFormStatus } from 'react-dom';
import type { ReactNode } from 'react';

interface SubmitButtonProps {
  children: ReactNode;
  loadingText?: string;
  className?: string;
}

export function SubmitButton({
  children,
  loadingText = 'Загрузка...',
  className = '',
}: SubmitButtonProps) {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      aria-disabled={pending}
      className={`submit-btn ${pending ? 'submit-btn--loading' : ''} ${className}`}
    >
      {pending ? loadingText : children}
    </button>
  );
}

Использование:

// В любой форме
<form action={someServerAction}>
  {/* ... поля ... */}
  <SubmitButton loadingText="Сохраняем профиль...">
    Сохранить профиль
  </SubmitButton>
</form>

// В другой форме
<form action={anotherAction}>
  {/* ... поля ... */}
  <SubmitButton loadingText="Отправляем...">
    Отправить сообщение
  </SubmitButton>
</form>

Как работает useFormStatus под капотом

useFormStatus использует React Context внутри реализации форм. Когда форма начинает отправку (через нативный механизм <form> или Server Action), React автоматически обновляет контекст формы, который потребляют все дочерние компоненты, использующие useFormStatus.

Это значит:

• Нет лишних ре-рендеров родительского компонента — статус обновляется только в тех компонентах, которые его используют.
• Автоматическая синхронизация — вам не нужно вручную управлять состоянием загрузки.
• Работает с нативными формами — хук реагирует на отправку <form> через action атрибут.

Важное ограничение: место вызова

useFormStatus должен вызываться внутри дочернего компонента формы, но не в компоненте самой формы.

// ❌ НЕПРАВИЛЬНО — useFormStatus вызывается в компоненте формы
function Form() {
  const { pending } = useFormStatus(); // Всегда вернёт { pending: false }!

  return (
    <form action={handleSubmit}>
      <button disabled={pending}>Отправить</button>
    </form>
  );
}

// ✅ ПРАВИЛЬНО — useFormStatus вызывается в дочернем компоненте
function SubmitButton() {
  const { pending } = useFormStatus(); // Корректно отслеживает форму

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Отправка...' : 'Отправить'}
    </button>
  );
}

function Form() {
  return (
    <form action={handleSubmit}>
      <SubmitButton /> {/* Корректный дочерний компонент */}
    </form>
  );
}

Поле action: работа с различными типами

Поле action из useFormStatus может принимать разные значения в зависимости от атрибута action формы.

import { useFormStatus } from 'react-dom';

function FormDebugInfo() {
  const { pending, method, action } = useFormStatus();

  if (!pending) return null;

  return (
    <div className="debug-info">
      <p>Метод: {method}</p>
      <p>
        Действие:{' '}
        {typeof action === 'function'
          ? 'Server Action'
          : action || 'не указано'}
      </p>
    </div>
  );
}

// Форма с URL в action
<form action="/api/submit" method="post">
  <FormDebugInfo /> {/* action = "/api/submit", method = "post" */}
  <SubmitButton />
</form>

// Форма с Server Action
<form action={serverAction}>
  <FormDebugInfo /> {/* action = [Function], method = "post" */}
  <SubmitButton />
</form>

Обработка ошибок и повторная отправка

useFormStatus автоматически возвращает pending: false после завершения отправки — независимо от успеха или ошибки. Для отображения ошибок используйте отдельное состояние или useActionState.

'use client';

import { useActionState } from 'react';
import { useFormStatus } from 'react-dom';
import { submitForm } from './actions';

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Отправка...' : 'Отправить'}
    </button>
  );
}

type FormState = {
  error?: string;
  success?: boolean;
};

export function ContactForm() {
  const [state, action] = useActionState<FormState, FormData>(
    submitForm,
    {}
  );

  return (
    <form action={action}>
      <input name="email" type="email" placeholder="Email" required />
      <textarea name="message" placeholder="Сообщение" required />

      {state.error && (
        <p className="error-message">{state.error}</p>
      )}

      {state.success && (
        <p className="success-message">Сообщение успешно отправлено!</p>
      )}

      <SubmitButton />
    </form>
  );
}

Сравнение useFormStatus с другими подходами

useFormStatus vs ручное управление состоянием

useFormStatus vs useActionState

Эти два хука дополняют друг друга:

• useFormStatus — отвечает на вопрос «форма сейчас отправляется?». Используется в дочерних компонентах для UI-реакции.
• useActionState (ранее useFormState) — управляет состоянием, которое возвращает Server Action. Используется в компоненте формы для работы с результатами.

'use client';

import { useActionState } from 'react';
import { useFormStatus } from 'react-dom';

// useFormStatus — для дочернего компонента (статус отправки)
function SubmitButton() {
  const { pending } = useFormStatus();
  return <button type="submit" disabled={pending}>Отправить</button>;
}

// useActionState — для компонента формы (результат действия)
function MyForm() {
  const [state, action] = useActionState(serverAction, null);

  return (
    <form action={action}>
      <input name="data" />
      {state?.error && <p>{state.error}</p>}
      <SubmitButton /> {/* Использует useFormStatus */}
    </form>
  );
}

Доступность (Accessibility)

При использовании useFormStatus важно не забывать об атрибутах доступности.

import { useFormStatus } from 'react-dom';

function AccessibleSubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      aria-disabled={pending}
      aria-busy={pending}
      aria-label={pending ? 'Форма отправляется, подождите' : 'Отправить форму'}
    >
      {pending ? (
        <>
          <span aria-hidden="true" className="spinner" />
          <span>Отправка...</span>
        </>
      ) : (
        'Отправить'
      )}
    </button>
  );
}

Атрибут aria-busy сообщает скринридерам, что элемент обновляется. Это улучшает опыт пользователей со вспомогательными технологиями.

Лучшие практики

1. Выносите кнопку в отдельный компонент

// ✅ Хорошо — кнопка переиспользуемая
function SubmitButton({ children }: { children: React.ReactNode }) {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Загрузка...' : children}
    </button>
  );
}

// ❌ Плохо — логика смешана с формой
function Form() {
  // Здесь useFormStatus не работает корректно
  return <form action={action}><button type="submit">Отправить</button></form>;
}

2. Используйте семантические атрибуты

Всегда добавляйте disabled и aria-disabled одновременно: disabled блокирует кнопку, а aria-disabled информирует вспомогательные технологии.

3. Показывайте визуальный фидбек

Пользователь должен всегда видеть, что происходит. Используйте спиннеры, анимации или смену текста.

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending} className="btn">
      {pending && <Spinner className="btn-spinner" />}
      <span>{pending ? 'Сохраняем...' : 'Сохранить'}</span>
    </button>
  );
}

4. Не злоупотребляйте полем data

Поле data содержит все данные формы. Не показывайте чувствительные данные (пароли, токены) в UI.

function FormStatus() {
  const { pending, data } = useFormStatus();

  if (!pending || !data) return null;

  // ✅ Безопасно — показываем только email
  const email = data.get('email');

  // ❌ Небезопасно — не показывайте пароли!
  // const password = data.get('password');

  return <p>Отправляем на {email as string}...</p>;
}

5. Комбинируйте с useActionState для полного контроля

useFormStatus + useActionState = полноценная обработка форм с загрузкой, результатами и ошибками.

Требования и совместимость

Примечание: useFormStatus появился в React 19. В React 18 он не работает. Для Next.js 13 с App Router в экспериментальном режиме была ограниченная поддержка, но стабильной она стала только с React 19.

Частые вопросы

Почему pending всегда false в моём компоненте?

Убедитесь, что компонент с useFormStatus является дочерним элементом <form>, а не самой формой. Хук не работает в компоненте, который рендерит саму форму.

Работает ли useFormStatus с обычным onSubmit?

useFormStatus работает только с формами, использующими нативный атрибут action (строка URL или Server Action). С onSubmit хук не обновляет pending.

Можно ли использовать useFormStatus в серверном компоненте?

Нет. useFormStatus — клиентский хук. Компонент, его использующий, должен иметь директиву 'use client'.

Что происходит при ошибке в Server Action?

Если Server Action выбрасывает ошибку, pending автоматически сбросится в false. Обрабатывайте ошибки через useActionState или try/catch внутри действия.

Итог

useFormStatus — это элегантное решение для отслеживания статуса отправки формы в React 19. Хук позволяет:

• Убрать prop drilling — дочерние компоненты сами получают нужный статус.
• Создавать переиспользуемые компоненты — универсальные кнопки, поля, индикаторы загрузки.
• Улучшать UX — пользователь всегда видит, что форма обрабатывается.
• Легко интегрироваться с Server Actions — особенно в Next.js App Router.

Хук прост в использовании, но важно помнить главное правило: вызывайте его только в дочерних компонентах формы, а не в самом компоненте с <form>. В паре с useActionState он даёт полный контроль над жизненным циклом отправки форм.

Хотите углубиться в React и научиться строить современные формы? Загляните на курс по React на PurpleSchool — там вы найдёте практические примеры и разберёте все аспекты работы с современными хуками React.