---
title: "React 19のform actionの使い方｜引数はFormData・よくある誤り"
url: "https://www.issoh.co.jp/tech/details/2851/"
published: 2024-06-28
updated: 2026-08-01
categories: ["React"]
publisher: "株式会社一創"
---

# React 19のform actionの使い方｜引数はFormData・よくある誤り

React 19では`<form>`の`action`プロパティに関数を渡せるようになり、送信処理を非同期関数として書けるようになりました。ところが、この関数は`onSubmit`のハンドラとは受け取る引数が違います。ここを取り違えたコードがそのまま動かない、というつまずきが多い機能です。この記事では、公式仕様で確定している挙動、useFormStatusとuseActionStateの役割分担、そして`onSubmit`を残したほうがよい場面を、動くコードで整理します。非同期処理そのものの考え方は[Async Reactの技術的背景](/tech/details/11005/)もあわせて参照してください。

## まとめ

- `action`に渡した関数の引数は**イベントではなくFormData**。`event.preventDefault()`は書かない（書くと実行時エラー）
- 送信中の表示は`useFormStatus`の`pending`、処理結果とエラーは`useActionState`の`state`。`isPending`はuseActionState側にしか無い
- 関数を渡すと`method`の指定に関わらずPOSTとして扱われ、成功時に**非制御フィールドだけ**が自動リセットされる
- 制御コンポーネント中心のフォームや、バリデーション基盤を導入済みのプロジェクトでは、`onSubmit`を残す判断が妥当な場面がある

以降は、この4点をreact.devの記述と動くコードで確認します。

## form actionに関数を渡したときの挙動

`action`プロパティは、文字列を渡すか関数を渡すかで意味が変わります。文字列を渡した場合は標準のHTMLフォームと同じく送信先URLとして扱われ、関数を渡した場合だけReactのAction（トランジション内で実行される送信処理）になります。同じプロパティ名で挙動が切り替わる点が、この機能を分かりにくくしている原因です。

### 引数はイベントではなくFormData

React DOMのformリファレンスは、関数を渡した場合について「送信されたフォームのFormDataを含む単一の引数で呼ばれる」と明記しています。`onSubmit`のハンドラのように`SubmitEvent`が渡されるわけではありません。したがって`event.preventDefault()`も`new FormData(event.target)`も不要で、書けばそこで落ちます。

```
// 誤り: action に渡した関数はイベントを受け取らない
async function submitContactNG(event) {
  event.preventDefault();                   // TypeError: event.preventDefault is not a function
  const data = new FormData(event.target);  // event.target は存在しない
}

// 正しい: 第1引数がそのまま FormData
async function submitContactOK(formData) {
  const email = formData.get("email");
}
```

入力値は`name`属性をキーにして`formData.get("email")`で取り出します。`get`の戻り値は文字列またはFileのため、そのまま文字列として扱う前に型を確認しておくと後述のTypeScript対応が楽になります。

### methodプロパティの扱いと非制御フィールドの自動リセット

関数を渡したフォームには、覚えておくべき挙動が2つあります。ひとつは、`method`プロパティに何を指定してもHTTPメソッドがPOSTとして扱われる点。ブラウザによるネイティブ送信そのものは起きず、実際の通信は関数内の`fetch`が担うので、GETのリクエストを投げること自体は自由です。影響が出るのは`useFormStatus`が返す`method`の値と、JavaScriptの読み込み前に送信された場合のネイティブ送信に頼る構成です。

もうひとつは、Actionが成功した後、フォーム内の非制御フィールドがReactによって自動的にリセットされること。対象は非制御フィールドだけで、値をstateで持つ制御コンポーネントは影響を受けません。リセットのタイミングを自分で決めたい場合は、React 19で追加された`requestFormReset`を使います。非制御フィールドの値をrefで読む書き方は[useRefによるDOM参照](/tech/details/3279/)の整理もあわせて確認してください。

## 非同期送信フォームの基本実装

最小構成は、非同期関数をそのまま`action`へ渡すだけです。React側で送信がトランジションとして扱われるため、送信中フラグを自前の`useState`で持つ必要はありません。

```
function ContactForm() {
  async function submitContact(formData) {
    const res = await fetch("/api/contact", {
      method: "POST",
      body: formData,
    });
    if (!res.ok) {
      throw new Error("送信に失敗しました");
    }
  }

  return (
    <form action={submitContact}>
      <input type="text" name="name" required />
      <input type="email" name="email" required />
      <button type="submit">送信</button>
    </form>
  );
}
```

FormDataをそのまま`fetch`のbodyへ渡せるので、送信前にオブジェクトへ詰め替える処理も消えます。関数内で例外が投げられた場合の行き先は、最も近いエラーバウンダリです。画面上にエラーメッセージを出したいのであれば、例外ではなく戻り値で結果を返す次の書き方に切り替えます。

## 送信中・結果・エラーの状態管理

状態管理のフックは2つあり、見る対象が違います。`useFormStatus`は親フォームの送信中かどうかだけを見るUI向けのフック、`useActionState`はAction本体をラップして戻り値を状態として保持するフックです。ボタンの無効化は前者、エラーメッセージの表示は後者、と分けて考えると迷いません。送信結果を待たずに画面へ反映する楽観的更新が必要なら`useOptimistic`が加わりますが、これは表示の先出しが要る場面だけの選択肢で、フォームのActionを使うために必須ではありません。

### useFormStatusによる送信中のボタン制御

`useFormStatus`が返すのは`pending`（boolean）、`data`（FormDataまたはnull）、`method`（getまたはpost）、`action`（親フォームに渡された関数またはnull）の4つです。`data`は送信中のFormDataなので、`data.get("email")`で送信内容をそのまま確認画面に出せます。`action`がnullになるのは、親フォームが無い場合、`action`プロパティを指定していない場合、そして`action`にURL文字列を渡した場合です。最大の注意点は、親の`<form>`しか見ないこと。`<form>`を返しているコンポーネント自身で呼んでも、その`<form>`の状態は取得できません。送信ボタンを子コンポーネントに切り出すのが定石です。

```
import { useFormStatus } from "react-dom";

async function submitContact(formData) {
  await fetch("/api/contact", { method: "POST", body: formData });
}

function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "送信中" : "送信"}
    </button>
  );
}

function ContactForm() {
  return (
    <form action={submitContact}>
      <input type="email" name="email" required />
      <SubmitButton />
    </form>
  );
}
```

インポート元が`react`ではなく`react-dom`である点も間違えやすいところです。

### useActionStateによる結果とエラーの受け取り

`useActionState`は`[state, formAction, isPending]`を返します。第1引数のAction関数が受け取るのは`(前回のstate, formData)`の2つで、その戻り値が次の`state`です。第2引数が初期state、第3引数は任意の`permalink`で、React Server Componentsでの段階的な強化（JavaScriptの読み込み前に送信された場合の遷移先）に使います。

```
import { useActionState } from "react";

async function submitContact(prevState, formData) {
  const res = await fetch("/api/contact", { method: "POST", body: formData });
  if (!res.ok) {
    return { message: "送信に失敗しました。時間をおいて再度お試しください。" };
  }
  return { message: "送信が完了しました。" };
}

function ContactForm() {
  const [state, formAction, isPending] = useActionState(submitContact, { message: "" });

  return (
    <form action={formAction}>
      <input type="email" name="email" required />
      <button type="submit" disabled={isPending}>送信</button>
      <p>{state.message}</p>
    </form>
  );
}
```

フォームに渡すのは元のAction関数ではなく、返ってきた`formAction`です。Action関数が例外を投げるとキュー内の後続Actionはキャンセルされエラーバウンダリへ飛ぶため、想定内の失敗はthrowせず戻り値で返す設計にします。

### pendingとisPendingの取り違え

送信中フラグの名前がフックによって違います。`useFormStatus`は`pending`、`useActionState`は配列の3番目として`isPending`を返します。`const { isPending } = useFormStatus()`と書いてもエラーにはならず、値が`undefined`になるだけです。ボタンの`disabled`が常に偽になり、二重送信が素通りします。型チェックが効かないJavaScriptのコードでは気づきにくいため、既存コードの移植時はここを最初に確認してください。

## actionとonSubmitの使い分け

React 19が出たからといって、既存の`onSubmit`をすべて置き換える必要はありません。両者は守備範囲が違います。

| 観点             | action に関数                     | onSubmit    |
| -------------- | ------------------------------ | ----------- |
| 引数             | FormData                       | SubmitEvent |
| preventDefault | 不要                             | 必要          |
| 送信中の状態         | useFormStatus / useActionState | 自前のuseState |
| 成功後の入力欄        | 非制御は自動リセット                     | 手動でリセット     |
| HTTPメソッド       | POST扱い（ネイティブ送信時）               | 制限なし        |

判断の分かれ目になりやすいのは、表の「引数」と「成功後の入力欄」の2行です。以下、移行して効果が出るケースと、残したほうがよいケースを分けます。

### actionへ移行して効果が出るフォーム

入力欄を非制御のまま扱っている問い合わせフォーム、検索条件の送信、コメント投稿のように「入力値を送って結果を受け取るだけ」のフォームは移行の効果が大きい対象です。`useState`による入力値の保持、送信中フラグ、送信後のリセット処理がまとめて不要になり、コンポーネントから状態が消えます。ファイルアップロードを含むフォームも、FormDataがそのまま手に入るぶん有利です。

### onSubmitを残すべきフォーム

移行しないほうがよい条件ははっきりしています。入力のたびに他の項目を書き換える、入力途中で候補を出す、といった**入力値を制御コンポーネントとして持つ必然性があるフォーム**です。この場合、値はどのみち`useState`側にあるためFormDataの利点が出ず、自動リセットの対象にもなりません。検索条件をクエリ文字列としてURLへ反映し、ブラウザの履歴や共有可能なURLを残したいフォームも、送信をJavaScript側で完結させるActionとは相性が悪い部類です。送信前に複数項目をまたぐバリデーションを行い、エラー時に送信そのものを止めたい設計でも、`onSubmit`で止めるほうが素直に書けます。「新機能だから」を理由に移行すると、リセット処理を自前で書き直すだけの作業になります。

## TypeScriptでの型定義

`action`へ直接渡す関数は、FormDataを1つ受け取り`void`または`Promise<void>`を返す形になります。`useActionState`を使う場合はAction関数側に型を書けば、`state`と`isPending`は推論されるため、フック呼び出しに型引数を書き足す必要はありません。

```
import { useActionState } from "react";

type ContactState = { message: string };

async function submitContact(
  prevState: ContactState,
  formData: FormData
): Promise<ContactState> {
  const email = formData.get("email");
  if (typeof email !== "string" || email === "") {
    return { message: "メールアドレスを入力してください。" };
  }
  await fetch("/api/contact", { method: "POST", body: formData });
  return { message: "送信が完了しました。" };
}

function ContactForm() {
  // state は ContactState、isPending は boolean に推論される
  const [state, formAction, isPending] = useActionState(submitContact, {
    message: "",
  });

  return (
    <form action={formAction}>
      <input type="email" name="email" required />
      <button type="submit" disabled={isPending}>送信</button>
      <p>{state.message}</p>
    </form>
  );
}
```

`formData.get()`の戻り値は`FormDataEntryValue | null`、つまり文字列かFileかnullです。上の例のように`typeof`で絞り込んでから使うと、値が空のときの分岐とバリデーションを同じ場所で書けます。React 19における型定義まわりの変更点は[childrenとpropsの型定義](/tech/details/4116/)の整理もあわせて確認しておくと移行時の手戻りが減ります。

## React Hook Form導入済みプロジェクトでの判断

すでにReact Hook Formなどのフォームライブラリを入れている場合、`action`は競合する機能ではなく、担当範囲が重なる部分があるだけです。ライブラリ側が強いのは入力単位のバリデーション、エラーメッセージの保持、条件付きの項目表示といった**送信前**の制御で、`action`とuseActionStateが担うのは**送信そのものと送信後**の状態です。

判断の目安は、そのフォームにバリデーションの要件がどれだけあるかです。項目が数個で必須チェック程度なら、ライブラリを外して`action`だけで組むと依存が1つ減ります。逆に項目間の相関チェックや動的な入力欄があるフォームは、ライブラリ側に送信までを任せたままにしたほうが安全です。両方を1つのフォームで混ぜる場合は、送信後に入力欄を空にする責任をどちらが持つかを先に決めてください。Reactの自動リセットとライブラリのリセットが二重に走ると、エラー表示だけが画面に残る状態になります。ライブラリ側の設計は[React Hook Formのバリデーション実装](/tech/details/2898/)で整理しています。

## よくある質問

### React Routerの`<Form>`のactionと同じものですか？

別のものです。React Routerが提供する`<Form>`コンポーネントの`action`は、送信先のルートを指すパスであり、そのルートに定義されたaction関数が実行されます。一方この記事で扱っているのはReact DOMの`<form>`要素そのもののプロパティで、渡すのは関数です。名前が同じで概念が違うため、React Routerを使っているプロジェクトでは、小文字の`<form>`とRouterの`<Form>`のどちらを書いているかを毎回確認してください。

### React 18でもactionに関数を渡せますか？

渡せません。フォームのActionはReact 19で追加された機能で、安定版のリリースは2024年12月5日です。React 18のまま関数を渡すと、`action`プロパティの値が不正であるという警告が出たうえで、属性自体がDOMに出力されません。結果としてフォームは送信先未指定の状態になり、送信時に現在のURLへネイティブ送信されてページが遷移します。2026年8月1日時点でnpmのreactパッケージのlatestは19.2.8なので、19系の最新へ上げれば利用できます。

### useFormStateはもう使えませんか？

`useActionState`は、Canary版で`ReactDOM.useFormState`という名前だったものを改称したものです。React 19では改称にあわせて`useFormState`が非推奨になりました。Canary版の情報を参照して書かれた記事やサンプルは古い名前のままのことがあるため、インポート元が`react-dom`の`useFormState`になっていたら、`react`からの`useActionState`へ読み替えてください。

### Server Functions（use server）は必須ですか？

必須ではありません。`action`に渡す関数はクライアント側の通常の非同期関数でよく、この記事のコード例もすべてクライアントだけで動きます。Server Functionsと組み合わせるとフォーム送信をサーバー側の関数に直結できますが、それはReact Server Componentsを使う構成での選択肢であり、フォームのActionを使うための前提条件ではありません。

### 送信ボタンごとに違う処理を実行できますか？

できます。`<form>`の`action`は、`<button>`や`<input type="submit">`、`<input type="image">`の`formAction`プロパティで上書き可能です。「投稿する」と「下書き保存」のように、同じ入力内容に対して行き先の違う処理を並べたい場合は、フォーム全体に既定のActionを置き、別処理のボタンにだけ`formAction`を指定します。

## 関連記事

- [React Hook Formとは？使い方・バリデーション・v7の書き方を実例で解説](/tech/details/2898/)
- [フロントエンド開発者が理解すべきAsync Reactの技術的背景と全体像](/tech/details/11005/)
- [Reactのchildrenとpropsの違い｜型定義・設計パターン・React 19の変更点](/tech/details/4116/)
- [ReactのuseRefの使い方｜useStateとの違い・DOM参照・値の保持を実例で解説](/tech/details/3279/)

---

出典: [React 19のform actionの使い方｜引数はFormData・よくある誤り](<https://www.issoh.co.jp/tech/details/2851/>)（株式会社一創）