useActionState и useFormStatus: ожидание и результат

Здесь будет встроен видео-разбор темы (5–7 минут, YouTube / RuTube / VK Видео) — тем, кто лучше воспринимает на слух, текст ниже не обязателен.

В части II отправка выглядела так: событие submit, preventDefault, сбор FormData, запрос. В React это тот же обработчик, только записанный в JSX. Меняется не он, а его окружение: вокруг одной отправки заводятся три состояния — ждём ли ответа, что вернулось и что показать, если не вышло.

Пример печатает в поле за читателя и жмёт кнопку сам. Прогноз перед запуском: сколько строк «рендер» окажется в выводе и что будет в поле, когда отправка закончится?

tsx

// сети в песочнице нет: задержку сервера честно изображаем таймером
function save(email: string): Promise<string> {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (email.includes("@")) resolve("сохранено: " + email);
      else reject(new Error("нужен адрес с собакой"));
    }, 300);
  });
}

function Subscribe() {
  const [pending, setPending] = React.useState(false);
  const [error, setError] = React.useState("");
  const [done, setDone] = React.useState("");
  console.log("рендер | ждём:", pending, "| ошибка:", error, "| итог:", done);

  const onSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    // данные снимаем до await: после него у события уже нет currentTarget
    const data = new FormData(event.currentTarget);
    setPending(true);
    setError("");
    try {
      setDone(await save(String(data.get("email") ?? "")));
    } catch (err) {
      setError((err as Error).message);
    } finally {
      // без finally одна ветка выхода оставит кнопку выключенной навсегда
      setPending(false);
    }
  };

  return (
    <form onSubmit={onSubmit}>
      <input name="email" defaultValue="" />
      <button id="send" disabled={pending}>{pending ? "отправляем…" : "подписаться"}</button>
      <p>{error || done}</p>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Subscribe />);

// печатаем в поле за читателя и жмём кнопку
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  field.value = "rico@java-script.pro";
  document.getElementById("send")!.click();
}, 100);
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  console.log("в поле осталось:", JSON.stringify(field.value));
}, 600);

// сети в песочнице нет: задержку сервера честно изображаем таймером
function save(email: string): Promise<string> {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (email.includes("@")) resolve("сохранено: " + email);
      else reject(new Error("нужен адрес с собакой"));
    }, 300);
  });
}

function Subscribe() {
  const [pending, setPending] = React.useState(false);
  const [error, setError] = React.useState("");
  const [done, setDone] = React.useState("");
  console.log("рендер | ждём:", pending, "| ошибка:", error, "| итог:", done);

return (
    <form onSubmit={onSubmit}>
      <input name="email" defaultValue="" />
      <button id="send" disabled={pending}>{pending ? "отправляем…" : "подписаться"}</button>
      <p>{error || done}</p>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Subscribe />);

// печатаем в поле за читателя и жмём кнопку
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  field.value = "rico@java-script.pro";
  document.getElementById("send")!.click();
}, 100);
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  console.log("в поле осталось:", JSON.stringify(field.value));
}, 600);

страница примера

Сначала предположите, что выведет код

разбор вывода
Три рендера: исходный, «ждём» и «пришёл ответ». Текст в поле остался: preventDefault отменил штатную отправку, и сбрасывать форму было некому.

Пример работает — и это важная оговорка: ни один хук этой статьи не делает того, чего нельзя написать руками. Разница в списке того, что приходится помнить самому: сбросить прошлую ошибку перед отправкой, вернуть pending в false во всех ветках выхода (одна забытая — и кнопка мертва до перезагрузки), выключить кнопку, чтобы второй клик не ушёл следом за первым.

Три значения, которые всегда меняются вместе, — тот самый случай из статьи про структуру состояния: их место в одном значении, а не в трёх переменных.

И последнее, что стоит заметить перед следующим разделом: preventDefault отдаёт отправку вашему обработчику, и формой дальше никто не занимается. В следующем разделе ею займётся React — и поведёт она себя иначе.

Хук берёт эти три состояния на себя. Ему передают функцию-действие и начальное значение, а он возвращает тройку.

Что вернулось	Что это
`state`	то, что действие вернуло в прошлый раз; до первой отправки — начальное значение
`formAction`	обёртка вокруг действия — её и передают в `action` формы
`isPending`	`true`, пока действие не закончилось

У самого действия подпись непривычная: первым аргументом приходит предыдущее состояние, вторым — FormData. Это редьюсер из статьи про useReducer, где роль «экшена» играют данные формы, — с одной поблажкой: ему разрешено быть асинхронным, и возвращённый промис React дождётся сам.

Прогноз: в каком порядке лягут строки вывода и что окажется в поле, когда действие закончится?

tsx

interface Result {
  ok: boolean;
  message: string;
}

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

// первым аргументом приходит ПРЕДЫДУЩЕЕ состояние, вторым — данные формы
async function subscribe(prev: Result, formData: FormData): Promise<Result> {
  console.log("действие пошло, прошлый ответ:", prev.message);
  const email = String(formData.get("email") ?? "");
  await wait(300); // здесь был бы запрос к серверу
  if (!email.includes("@")) return { ok: false, message: "нужен адрес с собакой" };
  return { ok: true, message: "подписан: " + email };
}

function Subscribe() {
  const [state, formAction, isPending] = React.useActionState(subscribe, {
    ok: false,
    message: "ещё не отправляли",
  });
  console.log("рендер | ждём:", isPending, "| ответ:", state.message);
  return (
    <form action={formAction}>
      <input name="email" defaultValue="" />
      <button id="send" disabled={isPending}>{isPending ? "отправляем…" : "подписаться"}</button>
      <p>{state.message}</p>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Subscribe />);

// печатаем в поле за читателя — теперь значение поля и defaultValue разные
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  field.value = "rico@java-script.pro";
  document.getElementById("send")!.click();
}, 100);
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  console.log("в поле осталось:", JSON.stringify(field.value));
}, 600);

interface Result {
  ok: boolean;
  message: string;
}

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

// первым аргументом приходит ПРЕДЫДУЩЕЕ состояние, вторым — данные формы
async function subscribe(prev: Result, formData: FormData): Promise<Result> {
  console.log("действие пошло, прошлый ответ:", prev.message);
  const email = String(formData.get("email") ?? "");
  await wait(300); // здесь был бы запрос к серверу
  if (!email.includes("@")) return { ok: false, message: "нужен адрес с собакой" };
  return { ok: true, message: "подписан: " + email };
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Subscribe />);

// печатаем в поле за читателя — теперь значение поля и defaultValue разные
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  field.value = "rico@java-script.pro";
  document.getElementById("send")!.click();
}, 100);
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  console.log("в поле осталось:", JSON.stringify(field.value));
}, 600);

страница примера

Сначала предположите, что выведет код

разбор вывода
Рендеров три — столько же, сколько было в версии руками. Строка «действие пошло» напечаталась раньше рендера с isPending: true. А поле в конце пустое.

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

С полем выходит неожиданность. Когда действие заканчивается, React сбрасывает форму — ровно как form.reset(): значения полей возвращаются к своим defaultValue. В примере из первого раздела мы отменили штатное поведение формы через preventDefault, и сбрасывать было некому; здесь формой снова занимается React.

Сброс происходит и после отказа: React не разбирает, что вернуло действие, — ему важно только то, что оно закончилось. В следующем разделе это видно своими глазами.

Ошибиться в подписи действия легко: рука сама пишет функцию, принимающую одну FormData. Компилятор про это знает — запустите и прочитайте диагностику целиком: он честно перебирает обе перегрузки useActionState и на каждой упирается в одно и то же — на месте первого параметра ждали состояние, а получили данные формы.

tsx

async function subscribe(formData: FormData): Promise<string> {
  return "подписан: " + String(formData.get("email") ?? "");
}

// компонент нарочно не монтируется: вопрос только в том, что скажет компилятор
function Subscribe() {
  const [state, formAction] = React.useActionState(subscribe, "ещё не отправляли");
  return (
    <form action={formAction}>
      <p>{state}</p>
    </form>
  );
}

страница примера

Сначала предположите, что выведет код

Сброс касается только неуправляемых полей — тех, что хранят значение в DOM. Управляемому полю из главы про формы reset() безразличен: значение в него приходит из состояния, и ближайший же рендер вернёт туда то, что лежит в переменной.

Отсюда простое правило выбора для форм с действием: если поле не нужно читать на каждый ввод — оставляйте его неуправляемым, FormData заберёт значение при отправке. Управляемым его делают ради живой проверки, счётчика символов или зависимых полей, а не ради самой отправки.

Действие может закончиться плохо двумя способами, и они не равны. Исключение — это поломка: его ловит ближайшая граница ошибок, компонент с формой при этом исчезает с экрана целиком. А в Next серверное действие, бросившее исключение в проде, отдаёт наружу общую фразу: текст ошибки на сервере остаётся в логах, чтобы вместе с ним наружу не уехало ничего лишнего.

Провалившаяся проверка — не поломка. Это нормальный, ожидаемый результат: адрес без собаки, занятое имя, слишком короткий пароль. Такой результат возвращают, а не бросают, — и он становится состоянием формы наравне с успехом.

Раз состояние одно, а исходов несколько, просится размеченное объединение из части III: поле-метка status, а рядом — только те данные, которые в этом исходе есть. Заодно решается вторая задача: форму React сбросит, и введённый адрес надо чем-то вернуть в поле. В примере два поля — адрес действие возвращает, а прозвище нет. Прогноз: что останется в каждом из них?

tsx

// состояние формы — размеченное объединение из части III: в каждом варианте
// ровно те поля, которые в нём осмысленны
type State =
  | { status: "idle"; email: string }
  | { status: "error"; email: string; message: string }
  | { status: "ok"; email: string };

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

async function subscribe(prev: State, formData: FormData): Promise<State> {
  const email = String(formData.get("email") ?? "");
  await wait(200);
  // отказ проверки — обычный результат действия, а не исключение
  if (!email.includes("@")) return { status: "error", email, message: "нужен адрес с собакой" };
  return { status: "ok", email };
}

function Subscribe() {
  const [state, formAction, isPending] = React.useActionState(subscribe, {
    status: "idle",
    email: "",
  });
  return (
    <form action={formAction}>
      <input name="email" defaultValue={state.email} />
      <input name="nick" defaultValue="" />
      <button id="send" disabled={isPending}>проверить</button>
      {state.status === "error" && <p>ошибка: {state.message}</p>}
      {state.status === "ok" && <p>подписан: {state.email}</p>}
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Subscribe />);

const поля = () => document.querySelectorAll("input");
// заполняем оба поля за читателя; адрес нарочно без собаки
setTimeout(() => {
  (поля()[0] as HTMLInputElement).value = "рико";
  (поля()[1] as HTMLInputElement).value = "Рико";
  document.getElementById("send")!.click();
}, 100);
setTimeout(() => {
  console.log("адрес:", JSON.stringify((поля()[0] as HTMLInputElement).value));
  console.log("прозвище:", JSON.stringify((поля()[1] as HTMLInputElement).value));
}, 600);

// состояние формы — размеченное объединение из части III: в каждом варианте
// ровно те поля, которые в нём осмысленны
type State =
  | { status: "idle"; email: string }
  | { status: "error"; email: string; message: string }
  | { status: "ok"; email: string };

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

async function subscribe(prev: State, formData: FormData): Promise<State> {
  const email = String(formData.get("email") ?? "");
  await wait(200);
  // отказ проверки — обычный результат действия, а не исключение
  if (!email.includes("@")) return { status: "error", email, message: "нужен адрес с собакой" };
  return { status: "ok", email };
}

function Subscribe() {
  const [state, formAction, isPending] = React.useActionState(subscribe, {
    status: "idle",
    email: "",
  });
  return (
    <form action={formAction}>
      <input name="email" defaultValue={state.email} />
      <input name="nick" defaultValue="" />
      <button id="send" disabled={isPending}>проверить</button>
      {state.status === "error" && <p>ошибка: {state.message}</p>}
      {state.status === "ok" && <p>подписан: {state.email}</p>}
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Subscribe />);

const поля = () => document.querySelectorAll("input");
// заполняем оба поля за читателя; адрес нарочно без собаки
setTimeout(() => {
  (поля()[0] as HTMLInputElement).value = "рико";
  (поля()[1] as HTMLInputElement).value = "Рико";
  document.getElementById("send")!.click();
}, 100);
setTimeout(() => {
  console.log("адрес:", JSON.stringify((поля()[0] as HTMLInputElement).value));
  console.log("прозвище:", JSON.stringify((поля()[1] as HTMLInputElement).value));
}, 600);

страница примера

Сначала предположите, что выведет код

разбор вывода
Адрес остался, прозвище пропало.

Оба исхода объясняются одинаково. Форма сбросилась к своим defaultValue: у прозвища это пустая строка, а у адреса — значение из нового состояния, которое только что вернуло действие. Сброс и новое состояние приезжают одним коммитом, поэтому читатель видит свой текст на месте, а под формой — причину отказа. Заодно подтвердилось и то, что обещала пометка выше: действие вернуло ошибку, а форма всё равно сбросилась.

Отсюда правило: всё, что должно пережить отправку, действие обязано вернуть. Что не вернули — то и пропало вместе со сбросом.

Так писать не нужно, но знать, что будет, полезно: промис действия отклоняется, React отдаёт ошибку ближайшей границе, и вместо формы читатель видит запасную разметку. Ни state, ни isPending ему уже не помогут.

tsx

async function subscribe(prev: string, formData: FormData): Promise<string> {
  const email = String(formData.get("email") ?? "");
  if (!email.includes("@")) throw new Error("нужен адрес с собакой");
  return "подписан: " + email;
}

function Subscribe() {
  const [state, formAction, isPending] = React.useActionState(subscribe, "ещё не отправляли");
  console.log("рендер | ждём:", isPending, "| ответ:", state);
  return (
    <form action={formAction}>
      <input name="email" defaultValue="" />
      <button id="send" disabled={isPending}>подписаться</button>
      <p>{state}</p>
    </form>
  );
}

interface BoundaryProps {
  children?: React.ReactNode;
}

interface BoundaryState {
  error: Error | null;
}

// граница из главы про свои хуки и ошибки
class ErrorBoundary extends React.Component<BoundaryProps, BoundaryState> {
  state: BoundaryState = { error: null };

  static getDerivedStateFromError(error: Error): BoundaryState {
    return { error };
  }

  // печатаем здесь, а не в render: render React вправе вызвать не один раз
  componentDidCatch(error: Error) {
    console.log("граница поймала:", error.message);
  }

  render() {
    if (this.state.error) return <p>Форма не открылась</p>;
    return this.props.children;
  }
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <ErrorBoundary>
    <Subscribe />
  </ErrorBoundary>,
);

// адрес нарочно без собаки
setTimeout(() => {
  (document.querySelector("input") as HTMLInputElement).value = "рико";
  document.getElementById("send")!.click();
}, 100);

async function subscribe(prev: string, formData: FormData): Promise<string> {
  const email = String(formData.get("email") ?? "");
  if (!email.includes("@")) throw new Error("нужен адрес с собакой");
  return "подписан: " + email;
}

interface BoundaryProps {
  children?: React.ReactNode;
}

interface BoundaryState {
  error: Error | null;
}

// граница из главы про свои хуки и ошибки
class ErrorBoundary extends React.Component<BoundaryProps, BoundaryState> {
  state: BoundaryState = { error: null };

static getDerivedStateFromError(error: Error): BoundaryState {
    return { error };
  }

// печатаем здесь, а не в render: render React вправе вызвать не один раз
  componentDidCatch(error: Error) {
    console.log("граница поймала:", error.message);
  }

render() {
    if (this.state.error) return <p>Форма не открылась</p>;
    return this.props.children;
  }
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <ErrorBoundary>
    <Subscribe />
  </ErrorBoundary>,
);

// адрес нарочно без собаки
setTimeout(() => {
  (document.querySelector("input") as HTMLInputElement).value = "рико";
  document.getElementById("send")!.click();
}, 100);

страница примера

Сначала предположите, что выведет код

Пример так и устроен: форма обёрнута в границу из главы про свои хуки и ошибки. На экране — её запасная разметка, а последний рендер формы в выводе так и остался с isPending: true. Граница — правильное место для неожиданного: база не ответила, код упал на непредусмотренном случае. Для предусмотренного отказа есть возвращаемое значение.

isPending из прошлого раздела живёт в компоненте, который владеет формой. В настоящем проекте кнопка отправки — общий компонент на весь проект: с иконкой, размерами, блокировкой. Пробрасывать в неё пропс из каждой формы значит помнить об этом в каждой форме — и однажды забыть.

useFormStatus отдаёт состояние отправки ближайшей формы сверху. Импортируется он из react-dom, а не из react, и это не случайность: хук знает про <form> — то есть про разметку браузера, а не про React вообще.

tsxлистинг · не запускается

import { useFormStatus } from "react-dom";

// правильно: компонент отрисован ВНУТРИ формы и читает её статус
function SubmitButton() {
  const status = useFormStatus();
  return <button disabled={status.pending}>{status.pending ? "отправляем…" : "подписаться"}</button>;
}

interface SubscribeFormProps {
  action: (formData: FormData) => void;
}

function SubscribeForm({ action }: SubscribeFormProps) {
  // а здесь всегда false: свой хук этот компонент вызывает выше формы,
  // которую сам же и рисует
  const wrong = useFormStatus();
  console.log("владелец формы видит pending:", wrong.pending);
  return (
    <form action={action}>
      <input name="email" />
      <SubmitButton />
    </form>
  );
}

import { useFormStatus } from "react-dom";

// правильно: компонент отрисован ВНУТРИ формы и читает её статус
function SubmitButton() {
  const status = useFormStatus();
  return <button disabled={status.pending}>{status.pending ? "отправляем…" : "подписаться"}</button>;
}

interface SubscribeFormProps {
  action: (formData: FormData) => void;
}

function SubscribeForm({ action }: SubscribeFormProps) {
  // а здесь всегда false: свой хук этот компонент вызывает выше формы,
  // которую сам же и рисует
  const wrong = useFormStatus();
  console.log("владелец формы видит pending:", wrong.pending);
  return (
    <form action={action}>
      <input name="email" />
      <SubmitButton />
    </form>
  );
}

вывод · консоль браузера
владелец формы видит pending: false

Этот пример — листинг: песочница отдаёт глобально react и react-dom/client, а useFormStatus лежит в самом react-dom, которого здесь нет. Вывод под кодом снят с настоящего React 19. Пока идёт отправка, владелец формы не перерисовывается вовсе — «отправляем…» показывает только кнопка. Всё остальное в статье запускается по-настоящему.

Правило звучит странно ровно до того момента, пока не вспомнить, чем является статус формы. Это контекст, и провайдер в нём — сама <form>. Компонент, который эту форму рисует, стоит выше провайдера, а хук читает контекст с того места, где вызван. Соберём ту же расстановку руками — на обычном createContext из главы про общее состояние.

tsx

interface Status {
  pending: boolean;
}

// «форма» кладёт свой статус в контекст
const FormStatus = React.createContext<Status>({ pending: false });

interface ReaderProps {
  who: string;
}

function Reader({ who }: ReaderProps) {
  const status = React.useContext(FormStatus);
  console.log(who, "видит pending:", status.pending);
  return <p>{who}: {String(status.pending)}</p>;
}

function FakeForm() {
  const own = React.useContext(FormStatus);
  console.log("сама форма видит pending:", own.pending);
  return (
    <FormStatus value={{ pending: true }}>
      <Reader who="кнопка внутри формы" />
    </FormStatus>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<FakeForm />);

страница примера

Сначала предположите, что выведет код

Две строки в выводе — и обе честные: провайдер отдаёт значение вниз, а не вбок и не вверх. С useFormStatus происходит ровно это, разница только в том, что провайдера в разметке не видно: его ставит сам React вокруг содержимого формы.

Возвращает хук не одно поле, а объект — и объект этот тоже размеченное объединение.

Поле	Пока идёт отправка	В покое
`pending`	`true`	`false`
`data`	`FormData` отправляемой формы	`null`
`method`	`"get"` или `"post"`	`null`
`action`	функция или адрес из атрибута	`null`

Меткой служит pending, и компилятор относится к этому серьёзно: пока проверки нет, data для него — возможный null. Сужение по метке вы разбирали в части III; здесь оно приходит вместе с чужой библиотекой, само собой.

tsx

interface StatusPending {
  pending: true;
  data: FormData;
}
interface StatusIdle {
  pending: false;
  data: null;
}
type FormStatus = StatusPending | StatusIdle;

function label(status: FormStatus): string {
  return "отправляем " + String(status.data.get("email"));
}

страница примера

Сначала предположите, что выведет код

Поле data — приятная мелочь: пока отправка идёт, из него можно достать то, что уходит на сервер, и показать это читателю («сохраняем Рико…»), не заводя ради одной строки отдельное состояние.

Действие React запускает внутри перехода — того самого, из статьи про useTransition. Отсюда и isPending: это признак незавершённого перехода, а не отдельная бухгалтерия для форм. Отсюда же ответ на вопрос, что будет, если нажать «отправить» дважды подряд.

Прогноз: второе действие отменит первое, запустится параллельно с ним или дождётся его конца? И что оно увидит в prev?

tsx

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

async function push(prev: string[], formData: FormData): Promise<string[]> {
  const value = String(formData.get("v") ?? "");
  console.log("старт «" + value + "», прошлое состояние:", JSON.stringify(prev));
  await wait(300);
  return [...prev, value];
}

function Queue() {
  const [items, formAction, isPending] = React.useActionState(push, [] as string[]);
  console.log("рендер | ждём:", isPending, "| накоплено:", JSON.stringify(items));
  return (
    <form action={formAction}>
      <input name="v" defaultValue="" />
      <button id="send">отправить</button>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Queue />);

const send = (value: string) => {
  (document.querySelector("input") as HTMLInputElement).value = value;
  document.getElementById("send")!.click();
};
// второй клик уходит, пока первое действие ещё в пути
setTimeout(() => send("первое"), 100);
setTimeout(() => send("второе"), 150);

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

async function push(prev: string[], formData: FormData): Promise<string[]> {
  const value = String(formData.get("v") ?? "");
  console.log("старт «" + value + "», прошлое состояние:", JSON.stringify(prev));
  await wait(300);
  return [...prev, value];
}

function Queue() {
  const [items, formAction, isPending] = React.useActionState(push, [] as string[]);
  console.log("рендер | ждём:", isPending, "| накоплено:", JSON.stringify(items));
  return (
    <form action={formAction}>
      <input name="v" defaultValue="" />
      <button id="send">отправить</button>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Queue />);

const send = (value: string) => {
  (document.querySelector("input") as HTMLInputElement).value = value;
  document.getElementById("send")!.click();
};
// второй клик уходит, пока первое действие ещё в пути
setTimeout(() => send("первое"), 100);
setTimeout(() => send("второе"), 150);

страница примера

Сначала предположите, что выведет код

разбор вывода
Второе действие стартовало, когда первое закончилось, и получило его результат первым аргументом — поэтому в состоянии оказались оба значения, а не последнее. Промежуточный результат на экран не попал: рендера со списком из одного значения в выводе нет, React показал новое состояние, когда очередь опустела.

Действия одной формы выстраиваются в очередь и выполняются по одному. Гонки, из-за которой ответ на первый запрос перезаписывает ответ на второй, здесь не бывает: параллельных действий у одной формы просто нет.

Очередь — не повод не выключать кнопку. Пользователь, нажавший трижды, отправит форму трижды: React выполнит все три действия подряд, а сервер запишет три подписки.

Три хука рядом легко перепутать, поэтому короткая шпаргалка: что берут, когда нужно узнать про ожидание.

Что нужно	Чем брать	Где вызывать
Ожидание и ответ формы там, где форма объявлена	`useActionState`	в компоненте с `<form>`
Ожидание в кнопке или подсказке внутри формы	`useFormStatus`	в потомке `<form>`
Ожидание того, что формой не является	`useTransition`	где угодно

Ничего из этого не принадлежит Next: оба хука — часть React 19, и примеры выше запустились в обычном браузере, без сервера и маршрутов. Next меняет только природу действия: вместо функции, живущей рядом с компонентом, в action уходит серверная функция из прошлой статьи. Подпись, очередь, сброс формы и useFormStatus при этом работают ровно так же.

У серверного действия есть свойство, которого нет у обычной функции: браузер умеет отправить такую форму сам, обычным POST, ещё до того как React в браузере ожил. Поэтому у полей должны быть настоящие name — данные собирает не ваш код, а браузер.

У useActionState для этого случая есть третий аргумент — permalink: адрес, на который браузер уйдёт, если форму отправили до того, как загрузился и ожил JavaScript. Без него такая отправка вернёт читателя на текущий адрес, что для страницы с динамическим содержимым не всегда то, что нужно.

useActionState(действие, начальное) возвращает тройку: состояние, обёрнутое действие для action формы и признак ожидания.
Действие — асинхронный редьюсер: первым аргументом предыдущее состояние, вторым FormData, а возвращённое значение становится новым состоянием.
Отказ проверки возвращают, а не бросают: исключение уходит к границе ошибок и в проде теряет текст.
После действия React сбрасывает форму, поэтому всё, что должно пережить отправку, действие обязано вернуть — и подставить в defaultValue.
useFormStatus живёт в react-dom и отдаёт статус ближайшей формы сверху: вызывать его нужно в потомке <form>, а не там, где форма объявлена.
Действия одной формы выстраиваются в очередь и выполняются по одному, передавая друг другу результат.

1/4Что действие, переданное в useActionState, получает первым аргументом?

2/4useFormStatus вызван в том же компоненте, где написан <form>. Что вернёт pending во время отправки?

3/4Действие проверило адрес и хочет сообщить форме «нужен адрес с собакой». Как это сделать?

4/4Неуправляемое поле, форма с action={formAction}. Что станет с введённым текстом, когда действие завершится?

Убрать три состояния

Форма ниже написана вручную: два useState, preventDefault и сбор FormData в обработчике. Перепишите её на useActionState так, чтобы в компоненте не осталось ни одного useState, а поведение сохранилось: кнопка выключена на время отправки, под формой видно сообщение.

tsx

// перепишите на useActionState: состояний должно остаться ноль
function Rename() {
  const [pending, setPending] = React.useState(false);
  const [message, setMessage] = React.useState("");
  const onSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    setPending(true);
    const name = String(data.get("name") ?? "");
    await new Promise((resolve) => setTimeout(resolve, 300));
    setMessage(name.length < 2 ? "имя слишком короткое" : "теперь вас зовут " + name);
    setPending(false);
  };
  return (
    <form onSubmit={onSubmit}>
      <input name="name" defaultValue="Р" />
      <button id="send" disabled={pending}>сохранить</button>
      <p>{message}</p>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Rename />);
setTimeout(() => document.getElementById("send")!.click(), 100);

страница примера

Сначала предположите, что выведет код

Обработчик превращается в действие: событие ему не нужно, FormData приходит вторым аргументом, а сообщение оно просто возвращает.

tsxлистинг · не запускается

async function rename(prev: string, formData: FormData): Promise<string> {
  const name = String(formData.get("name") ?? "");
  await new Promise((resolve) => setTimeout(resolve, 300));
  return name.length < 2 ? "имя слишком короткое" : "теперь вас зовут " + name;
}

function Rename() {
  const [message, formAction, isPending] = React.useActionState(rename, "");
  return (
    <form action={formAction}>
      <input name="name" defaultValue="Р" />
      <button id="send" disabled={isPending}>сохранить</button>
      <p>{message}</p>
    </form>
  );
}

async function rename(prev: string, formData: FormData): Promise<string> {
  const name = String(formData.get("name") ?? "");
  await new Promise((resolve) => setTimeout(resolve, 300));
  return name.length < 2 ? "имя слишком короткое" : "теперь вас зовут " + name;
}

function Rename() {
  const [message, formAction, isPending] = React.useActionState(rename, "");
  return (
    <form action={formAction}>
      <input name="name" defaultValue="Р" />
      <button id="send" disabled={isPending}>сохранить</button>
      <p>{message}</p>
    </form>
  );
}

Заодно меняется одна деталь поведения: после отправки поле очистится — форму сбрасывает React. Если это нежелательно, введённое имя нужно вернуть из действия и подставить в defaultValue.

Кнопка без пропсов

Кнопка отправки — общий компонент на весь проект, и сейчас признак ожидания приходит в неё пропсом: каждая форма обязана про этот пропс помнить. Перепишите SubmitButton так, чтобы пропсов у неё не было вовсе, и объясните, почему тот же вызов внутри Form ничего бы не дал.

tsx

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

async function act(prev: string, formData: FormData): Promise<string> {
  await wait(300);
  return "готово: " + String(formData.get("v") ?? "");
}

interface SubmitButtonProps {
  pending: boolean; // пропс, от которого нужно избавиться
}

// кнопка одна на весь проект — и каждая форма обязана помнить про этот пропс
function SubmitButton({ pending }: SubmitButtonProps) {
  return <button id="send" disabled={pending}>{pending ? "отправляем…" : "отправить"}</button>;
}

function Form() {
  const [state, formAction, isPending] = React.useActionState(act, "—");
  return (
    <form action={formAction}>
      <input name="v" defaultValue="раз" />
      <SubmitButton pending={isPending} />
      <p>{state}</p>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Form />);
setTimeout(() => document.getElementById("send")!.click(), 100);

страница примера

Сначала предположите, что выведет код

Пропс исчезает, вместо него — хук; импорт идёт из react-dom, а не из react:

tsxлистинг · не запускается

import { useFormStatus } from "react-dom";

function SubmitButton() {
  const { pending } = useFormStatus();
  return <button id="send" disabled={pending}>{pending ? "отправляем…" : "отправить"}</button>;
}

import { useFormStatus } from "react-dom";

function SubmitButton() {
  const { pending } = useFormStatus();
  return <button id="send" disabled={pending}>{pending ? "отправляем…" : "отправить"}</button>;
}

Внутри Form тот же вызов всегда возвращал бы pending: false. Хук читает статус ближайшей формы сверху по дереву, а Form сам эту форму и рисует — то есть находится выше неё. Ожидание в Form берут из третьего элемента useActionState.

Вернуть введённое

Читатель ввёл адрес с опечаткой, действие вернуло отказ — и поле опустело: приходится набирать всё заново. Почините: после отказа адрес должен остаться в поле, после успеха — исчезнуть.

tsx

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

interface State {
  message: string;
}

async function subscribe(prev: State, formData: FormData): Promise<State> {
  const email = String(formData.get("email") ?? "");
  await wait(200);
  if (!email.includes("@")) return { message: "нужен адрес с собакой" };
  return { message: "подписан: " + email };
}

function Subscribe() {
  const [state, formAction, isPending] = React.useActionState(subscribe, { message: "" });
  return (
    <form action={formAction}>
      <input name="email" defaultValue="" />
      <button id="send" disabled={isPending}>подписаться</button>
      <p>{state.message}</p>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Subscribe />);

setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  field.value = "рико"; // опечатка: собаки нет
  document.getElementById("send")!.click();
}, 100);
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  console.log("в поле осталось:", JSON.stringify(field.value)); // сейчас ""
}, 600);

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

interface State {
  message: string;
}

async function subscribe(prev: State, formData: FormData): Promise<State> {
  const email = String(formData.get("email") ?? "");
  await wait(200);
  if (!email.includes("@")) return { message: "нужен адрес с собакой" };
  return { message: "подписан: " + email };
}

function Subscribe() {
  const [state, formAction, isPending] = React.useActionState(subscribe, { message: "" });
  return (
    <form action={formAction}>
      <input name="email" defaultValue="" />
      <button id="send" disabled={isPending}>подписаться</button>
      <p>{state.message}</p>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Subscribe />);

setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  field.value = "рико"; // опечатка: собаки нет
  document.getElementById("send")!.click();
}, 100);
setTimeout(() => {
  const field = document.querySelector("input") as HTMLInputElement;
  console.log("в поле осталось:", JSON.stringify(field.value)); // сейчас ""
}, 600);

страница примера

Сначала предположите, что выведет код

Состояние должно нести не только текст сообщения, но и то, что нужно вернуть в поле. Проще всего разметить исходы:

tsxлистинг · не запускается

type State =
  | { status: "idle" }
  | { status: "error"; email: string; message: string }
  | { status: "ok"; message: string };

async function subscribe(prev: State, formData: FormData): Promise<State> {
  const email = String(formData.get("email") ?? "");
  await wait(200);
  if (!email.includes("@")) {
    return { status: "error", email, message: "нужен адрес с собакой" };
  }
  return { status: "ok", message: "подписан: " + email };
}

type State =
  | { status: "idle" }
  | { status: "error"; email: string; message: string }
  | { status: "ok"; message: string };

async function subscribe(prev: State, formData: FormData): Promise<State> {
  const email = String(formData.get("email") ?? "");
  await wait(200);
  if (!email.includes("@")) {
    return { status: "error", email, message: "нужен адрес с собакой" };
  }
  return { status: "ok", message: "подписан: " + email };
}

В разметке поле берёт значение из состояния — в успешном исходе там пусто, и сброс оставит поле пустым:

tsxлистинг · не запускается

<input name="email" defaultValue={state.status === "error" ? state.email : ""} />

<input name="email" defaultValue={state.status === "error" ? state.email : ""} />

Обратите внимание: defaultValue здесь не «начальное значение раз и навсегда», а значение, к которому форма вернётся при следующем сбросе.

useActionState и useFormStatus: ожидание и результат

Видеоразбор темы за 5–7 минут

Три состояния рукамиЧто приходится держать вокруг одной отправки

useActionStateДействие возвращает состояние — как редьюсер, только асинхронный

Ошибка — это возвращённое значениеПочему её не бросают и как вернуть введённое обратно в поле

useFormStatusОжидание без пропсов — но только у потомка формы

Очередь, порядок и где чей pendingВторой клик поверх первого и три способа узнать про ожидание

Итогошпаргалка по теме

Проверьте себявопросы по теме

Задачизадачи с решениями

Убрать три состояния

Кнопка без пропсов

Вернуть введённое