useActionState и useFormStatus

useActionState(action, initialState) — это хук React 19, который оборачивает серверное действие и отслеживает его состояние между отправками. Он принимает функцию действия и начальное значение состояния, а возвращает кортеж, с помощью которого можно управлять всем взаимодействием с формой.

Хук возвращает [state, formAction, isPending]. В state хранится последнее возвращенное действием значение: изначально это null или заданное Вами начальное значение. formAction — обернутое действие, которое нужно передать форме. Значение isPending равно true, пока действие выполняется на сервере.

При каждой отправке формы серверное действие выполняется, а его возвращаемое значение становится новым значением state. При первой отрисовке state равно initialState. Благодаря этому легко отображать разный интерфейс в зависимости от того, были ли предыдущие отправки и какие результаты они вернули.

Если серверное действие возвращает { errors: { email: 'Invalid email' } }, Вы можете отобразить ошибку непосредственно в интерфейсе: {state.errors?.email && <p>{state.errors.email}</p>}. Поскольку состояние сохраняется между повторными отрисовками, сообщение об ошибке остается видимым, пока следующая успешная отправка не заменит это состояние.

Когда действие возвращает { success: true }, компонент может отобразить сообщение об успехе: {state?.success && <p>Form submitted!</p>}. В зависимости от значения состояния форму можно условно скрыть или заменить сообщением об успехе.

useFormStatus() — это хук, который считывает состояние ожидания ближайшего родительского элемента <form>. Он возвращает объект, включающий { pending: boolean }. Этот хук необходимо использовать внутри компонента, являющегося дочерним элементом формы, а не в компоненте, который сам отображает форму.

Ограничение, согласно которому useFormStatus нужно использовать внутри формы, существует потому, что хук считывает контекст формы из расположенного выше дерева React. Если вызвать его в том же компоненте, который отображает форму, он будет соседним элементом формы, а не ее потомком, и не получит доступ к состоянию формы.

Стандартный подход заключается в том, чтобы вынести кнопку отправки в отдельный компонент: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. Затем этот компонент размещается внутри формы и получает доступ к состоянию ожидания формы.

Установка disabled={pending} на кнопке отправки предотвращает повторную отправку. Когда пользователь нажимает кнопку отправки и серверное действие выполняется, значение pending равно true, поэтому кнопка отключается и становится недоступной для нажатия. После завершения действия значение pending снова становится равным false, и кнопка включается.

Полный подход к взаимодействию с формой объединяет оба хука: useActionState в компоненте формы отслеживает результат действия и предоставляет formAction, а useFormStatus внутри дочернего компонента SubmitButton отслеживает состояние ожидания. Вместе они обеспечивают отображение ошибок проверки и отзывчивую кнопку отправки.

Для еще более отзывчивого интерфейса useOptimistic используется вместе с useActionState. Вы сразу обновляете интерфейс ожидаемым результатом до ответа сервера, а затем синхронизируете его после получения фактического ответа. Этот подход часто используется в кнопках отметки «нравится», списках задач и других сценариях, требующих быстрой обратной связи.

Где нужно вызывать useFormStatus, чтобы он работал правильно?

useActionState(action, initialState) возвращает [state, formAction, isPending] для отслеживания результатов серверного действия. В состоянии хранится возвращаемое действием значение, благодаря чему можно отображать встроенные ошибки и сообщения об успехе. useFormStatus() предоставляет значение { pending } внутри дочерних компонентов формы, позволяя создавать отзывчивые кнопки отправки. Вместе оба хука обеспечивают полноценное и доступное взаимодействие с формой.